# Blesta

> Accept cryptocurrency payments in Blesta through Cryptonly hosted checkout.

**Cryptonly** lets your Blesta company accept Bitcoin, stablecoins, and other cryptocurrencies through Cryptonly's secure hosted checkout. Customers pay on the Cryptonly payment page. Blesta applies the settled amount only after a signed webhook.

***

## Requirements

| Requirement | Details |
| --- | --- |
| Blesta | 6.0 or newer (tested on 6.0.0 and 6.0.3) |
| PHP | 8.2, 8.3, or 8.4 |
| Cryptonly account | [cryptonly.net](https://cryptonly.net) merchant account |
| Credentials | API key and webhook signing key from the account’s **Accounts → Settings → Security** page |
| Public HTTPS URL | Required so Cryptonly can deliver webhooks. Cryptonly does not follow redirects |

***

## Before you install — Cryptonly account

1. Sign up at [cryptonly.net](https://cryptonly.net) (or [sandbox-merchant.cryptonly.net](https://sandbox-merchant.cryptonly.net) for testing).
2. Open **Accounts**, select the account, then **Settings → Security**. Create an **API key**. The key selects that account.
3. On the same page, under **Webhook signing key**, click **Rotate key** and copy the secret when it is shown. It appears only once, and the previous key stops working immediately.

***

## Install the gateway

1. Download the Cryptonly gateway from the [Blesta Marketplace](https://marketplace.blesta.com/extension/375).
2. Extract the archive in your Blesta root (FTP, SFTP, or your hosting file manager). The zip already contains the `components/` folder, so it merges with the existing one.

    After extraction, this file should exist:

    ```
    components/gateways/nonmerchant/cryptonly/cryptonly.php
    ```
3. In the Blesta staff area, open **Settings → Company → Payment Gateways → Available** and install **Cryptonly**.
4. Enable Cryptonly on the order form under **Packages → Order Forms**. Clients can also pay an open invoice from the client area.

***

## Configure the gateway

Open **Settings → Company → Payment Gateways → Installed**, choose **Manage** next to Cryptonly, and fill in the fields:

| Blesta field | What to enter |
| --- | --- |
| **API Key** | Cryptonly API key. The key selects the account. See [required scopes](https://docs.cryptonly.net/integration/plugins/blesta.md#api-key-scopes) |
| **Webhook Signing Key** | Required. Payments are confirmed only via webhooks |
| **Sandbox Mode** | Enable to use the Cryptonly sandbox API for testing |
| **Order ID Prefix** | Optional. Default `BLESTA` produces `BLESTA-12`, then `BLESTA-12-2` on a later attempt. Several invoices paid together use `BLESTA-12x34` |
| **Debug Log** | Optional. Writes entries to **Tools → Logs → Gateway** |

The settings page shows the **Webhook URL**. The gateway also sends that URL with each invoice, so you do not paste it into the Cryptonly dashboard.

Leave the API key or signing key blank on a later save to keep the stored value.

### API key scopes

Create the key on the account’s **Accounts → Settings → Security** page and enable only these scopes:

| Scope | Used for |
| --- | --- |
| `currencies.list` | Confirm the API key when saving the gateway (`GET /currencies`) and list the fiat currencies this gateway can be enabled for (`GET /currencies/fiat`) |
| `invoices.list` | Reuse a payable invoice or choose the next `orderId`, and load the invoice when create returns a duplicate (`GET /invoice`) |
| `invoices.create` | Create the invoice at checkout (`POST /invoice`) |

:::caution
**Webhook Signing Key is mandatory.** Saving an API key without a signing key is blocked. Sandbox mode must match your API key environment (sandbox vs production).
:::

Click **Update Settings**. The gateway validates the API key with Cryptonly `GET /currencies`.

***

## Test in sandbox

1. Enable **Sandbox Mode** and enter credentials from [sandbox-merchant.cryptonly.net](https://sandbox-merchant.cryptonly.net).
2. Confirm the Blesta URL Cryptonly will call is public HTTPS.
3. Create a test Blesta invoice and choose **Pay with Cryptonly**.
4. Complete payment on the Cryptonly hosted page (testnet only in sandbox), or use **Simulate payment** on the invoice in Cryptonly **Accounts → History** to settle it without sending testnet funds. See [Testing your integration](https://docs.cryptonly.net/guides/testing-your-integration.md).
5. Verify Blesta applied the payment and entries appear under **Tools → Logs → Gateway**.
6. Optional: in Cryptonly admin, use **Settings → Integration → Test webhooks** against your callback URL. See [Testing your integration](https://docs.cryptonly.net/guides/testing-your-integration.md).

See the Sandbox environment guide for supported test networks and safety notes.

***

## How Blesta invoices are updated

The gateway listens for `invoice.statusChanged` webhooks and applies payments only on settled amounts. Returning from the hosted page does not mark the invoice paid.

| Cryptonly invoice status | Blesta behavior |
| --- | --- |
| `created`, `processing` | No payment recorded. The customer may still pay on the hosted page |
| `suspended` | A pending transaction is recorded. No funds are applied |
| `paid`, `overpaid` | The amount still due is applied. An overpay is not added as client credit |
| `partially_paid` | `settlement.amountPaid` is applied and the invoice stays open. The next checkout starts a new Cryptonly invoice for the remainder |
| `expired`, `failed`, `cancelled` | No payment recorded. A later `paid` after `expired` can still be applied |

Cryptonly invoice expiry follows the Blesta due date, from 15 minutes up to 30 days.

:::caution
Sandbox uses testnets only. Do not send mainnet funds to sandbox payment addresses.
:::

The gateway does not send refunds or voids to Cryptonly. Record those in Blesta separately.

***

## Go live checklist

Before accepting real payments:

* [ ] Disable **Sandbox Mode**
* [ ] Enter production **API Key** and **Webhook Signing Key**
* [ ] Confirm the Blesta site URL is public HTTPS
* [ ] Place a small real test payment and confirm the invoice is paid

***

## Related documentation

  <ExternalLinkCard title="Blesta Marketplace listing" href="https://marketplace.blesta.com/extension/375" />
- [Webhooks](https://docs.cryptonly.net/api-reference/webhooks.md): Verification and payload details
- [Invoices](https://docs.cryptonly.net/guides/invoices.md): How checkout payments work
- [Testing your integration](https://docs.cryptonly.net/guides/testing-your-integration.md): History and test webhooks

***

## Support

For help with your Cryptonly merchant account, credentials, or payment questions, visit [Cryptonly](https://cryptonly.net) or write to support@cryptonly.net.