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

Sign up at cryptonly.net (or sandbox-merchant.cryptonly.net for testing).
Open Accounts, select the account, then Settings → Security. Create an API key. The key selects that account.
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

Download the Cryptonly WHMCS gateway zip (WHMCS Marketplace or release package).
Extract the archive on your computer.
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
```
In WHMCS admin, activate Cryptonly:
- Setup → Payments → Payment Gateways, or
- System Settings → Apps & Integrations (search “Cryptonly”).

Configure the gateway

WHMCS gateway settings

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
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`)

Click Save Changes. The module validates the API key with Cryptonly GET /currencies.

Test in sandbox

Enable Sandbox Mode and enter credentials from sandbox-merchant.cryptonly.net.
Confirm Setup → General Settings → System URL is a public HTTPS address.
Create a test WHMCS invoice and select Cryptonly as the payment method.
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.
Verify the WHMCS invoice is marked Paid and entries appear under Utilities → Logs → Gateway Log.
Optional: in Cryptonly admin, use Settings → Integration → Test webhooks against your callback URL — see Testing your integration.

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.

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

InvoicesHow checkout payments work

WebhooksVerification and payload details

SandboxTest with testnet funds

Testing your integrationHistory and simulated invoice payments

Support

For help with your Cryptonly merchant account, credentials, or payment questions, visit Cryptonly or write to [email protected].