> For the complete documentation index, see [llms.txt](https://cryptonly.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cryptonly.gitbook.io/docs/integration/cms-plugins/whmcs.md).

# 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, Account ID, and Webhook Signing Key from Cryptonly admin |
| 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. Create an **API key**: **Settings → Security → API keys**.
3. Copy your **Account ID**: **Accounts → select account → copy icon**.
4. Copy your **Webhook Signing Key**: **Settings → Security**.

***

#### Install the module

{% embed url="<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

<figure><img src="/files/ubxaLvulB4dnY6IUkbHa" alt=""><figcaption></figcaption></figure>

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 tenant API key                                        |
| **Account ID**          | Cryptonly account UUID                                          |
| **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**  |

{% hint style="warning" %}
**Webhook Signing Key is mandatory.** Saving an API key and Account ID without a signing key is blocked. Sandbox mode must match your API key environment (sandbox vs production).
{% endhint %}

Click **Save Changes**. The module validates your API key and Account ID against Cryptonly `GET /accounts`.

***

#### 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](/docs/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](/docs/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.

{% hint style="warning" %}
Sandbox uses testnets only. Do not send mainnet funds to sandbox payment addresses.
{% endhint %}

***

#### Go live checklist

Before accepting real payments:

* [ ] Disable **Sandbox Mode**
* [ ] Enter production **API Key**, **Account ID**, 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

* [Webhooks](/docs/integration/webhooks.md)
* [Invoices](/docs/guides/invoices.md)
* [Testing your integration](/docs/guides/testing-your-integration.md)

***

#### Support

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cryptonly.gitbook.io/docs/integration/cms-plugins/whmcs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.