# WHMCS

**Cryptonly** lets your WHMCS store accept Bitcoin, stablecoins and other cryptocurrencies through Cryptonly's secure hosted checkout. Customers pay on the Cryptonly payment page; WHMCS invoices are marked paid automatically.

***

## Requirements

| Requirement             | Details                                                           |
| ----------------------- | ----------------------------------------------------------------- |
| WHMCS                   | 8.0 or higher (tested up to 9.0.5)                                |
| PHP                     | 7.4 or higher (tested up to 8.2)                                  |
| 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 System URL | Required so Cryptonly can deliver webhooks                        |

***

## 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 module

[https://cdn.cryptonly.net/plugins/whmcs/cryptonly-whmcs-stable.zip](https://cdn.cryptonly.net/plugins/whmcs/cryptonly-whmcs-stable.zip)

1. Download the Cryptonly WHMCS gateway zip (WHMCS Marketplace or release package).
2. Extract the archive on your computer.
3. Upload the `modules/` folder into your WHMCS root so it merges with the existing `modules/` directory (FTP, SFTP, or your hosting file manager).

   After upload, these paths should exist:

   ```
   modules/gateways/cryptonly.php
   modules/gateways/cryptonly/
   modules/gateways/callback/cryptonly.php
   ```

4. In WHMCS admin, activate **Cryptonly**:

   * **Setup → Payments → Payment Gateways**, or
   * **System Settings → Apps & Integrations** (search "Cryptonly").

***

## Configure the gateway

![WHMCS gateway settings](./whmcs-gateway.png)

Open **Setup → Payments → Payment Gateways → Cryptonly → Manage Existing Gateway** and fill in the fields:

| WHMCS field             | What to enter                                                            |
| ----------------------- | ------------------------------------------------------------------------ |
| **Display Name**        | Name shown to customers (e.g. `Pay with Crypto`)                         |
| **API Key**             | Cryptonly API key. The key selects the account. See [required scopes](https://docs.cryptonly.net/integration/plugins/whmcs.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 `WHMCS` → `WHMCS-123`, `WHMCS-123-2` on retry          |
| **Debug Log**           | Optional; writes entries to **Utilities → Logs → Gateway Log**           |

### 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`)                                                             |
| `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 **Save Changes**. The module 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 **Setup → General Settings → System URL** is a public HTTPS address.
3. Create a test WHMCS invoice and select Cryptonly as the payment method.
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 the WHMCS invoice is marked **Paid** and entries appear under **Utilities → Logs → Gateway Log**.
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 WHMCS invoice statuses are updated

The module listens for `invoice.statusChanged` webhooks and applies payments only on settled amounts. Other statuses are logged to **Utilities → Logs → Gateway Log** without changing the WHMCS invoice:

| Cryptonly invoice status         | WHMCS behavior                                                       |
| -------------------------------- | -------------------------------------------------------------------- |
| `created`                        | Invoice stays **Unpaid** (customer may still pay on the hosted page) |
| `processing`, `suspended`        | Invoice stays **Unpaid**; status logged only                         |
| `paid`, `overpaid`               | Payment applied; invoice marked **Paid** when balance is cleared     |
| `partially_paid`                 | Partial payment applied to the WHMCS invoice                         |
| `expired`, `failed`, `cancelled` | Logged only; no automatic payment                                    |

The WHMCS invoice stays **Unpaid** from checkout until Cryptonly reports a settled payment (`paid`, `overpaid`, or `partially_paid`). There is no separate webhook when the customer only selects a currency on the hosted page.

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

***

## Go live checklist

Before accepting real payments:

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

***

## Related documentation

- [Invoices](https://docs.cryptonly.net/guides/invoices.md): How checkout payments work
- [Webhooks](https://docs.cryptonly.net/api-reference/webhooks.md): Verification and payload details
- [Sandbox](https://docs.cryptonly.net/guides/sandbox-environment.md): Test with testnet funds
- [Testing your integration](https://docs.cryptonly.net/guides/testing-your-integration.md): History and simulated invoice payments

***

## Support

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