Guides

WHMCS

A payment gateway for WHMCS: clients pay invoices in bitcoin or USDC/USDT straight to your wallet, marked paid by a signed webhook.

View as Markdown

The Perly Pay module adds crypto to your WHMCS invoices. The client presses Pay with crypto; the invoice's balance becomes an invoice in Perly Pay, paid over the WHMCS page or on its own; a signed webhook records the payment in WHMCS. WHMCS 8, PHP 8.1+ with curl. Nothing to install with Composer: the PHP SDK is inside.

Perly Pay bills in USD or EUR. For clients in another currency, set the gateway's Convert To For Processing to USD or EUR; the payment is still recorded in the invoice's own currency. Without it, those clients see a note to choose another way to pay.

Install

1
Get the zip
The module is on its way to the WHMCS Marketplace. Until it is listed, write to us for perly-pay-whmcs.zip.
2
Upload
Unzip it over your WHMCS folder. It adds modules/gateways/perlypay.php, modules/gateways/callback/perlypay.php and modules/gateways/perlypay/.
3
Activate
Configuration → Apps & Integrations → Payment Gateways (or Setup → Payment Gateways), activate Perly Pay.

Settings

Setting	What to put
Secret key	From Dashboard → Developers → API keys. `sk_test_…` for test mode, `sk_live_…` for real money.
Webhook signing secret	`whsec_…`, from the webhook you add for this WHMCS (below).
Payment page	Overlay opens the checkout over the invoice (pay.js). Redirect sends the client to it. Phones always get the page itself.
Currencies	USD and EUR, or only one of them.

1
Paste the key
Save, then press Test connection in the key's field: it says whether the key works, its mode, and whether this WHMCS's webhook is in Perly Pay.
2
Add the webhook
In Dashboard → Developers → Webhooks, add the address the settings show, https://your-whmcs/modules/gateways/callback/perlypay.php, with the invoice and refund events. Paste its secret and save.
3
Allow the overlay
In Dashboard → Settings, add your WHMCS address to Sites that may embed the checkout. Without it the overlay offers to open the checkout in a new tab.

Test

With a sk_test_… key, open an unpaid invoice in the client area and press Pay with crypto. Pay it with test coins, or from the API — the invoice's id is on the checkout page:

bash

curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'

Within seconds the WHMCS invoice is Paid. Billing → Gateway Log shows the network, the amount and a link to the transaction.

How invoices follow payments

In Perly Pay	In WHMCS
Paid and the sender checked (`invoice.fulfilled`)	A payment for the balance the client was billed, in the invoice's currency, under the Perly Pay payment id (`pay_…`). WHMCS marks the invoice Paid and does the rest as usual.
Seen, part paid, paid but still screening	A Gateway Log line. No payment.
Held for review	A Gateway Log line with the reason. Decide in Perly Pay.
Expired or canceled	A Gateway Log line. Pressing the button again makes a new invoice.
Refund opened, ready, sent, confirmed	A Gateway Log line, with what to send where.

Pressing the button again reuses the open invoice while the balance is the same. Each payment is recorded once, however often the webhook arrives, and only for invoices this WHMCS made.

Refunds

Refund the transaction in WHMCS as usual: the module opens a refund in Perly Pay, in the coin that was paid (the same share of it for part). Perly Pay emails the client for an address and checks it; the Gateway Log then says what to send where. You send from your wallet and paste the transaction id in Perly Pay — Perly Pay never holds the money.

Go live

Turn on live mode in Perly Pay and connect your wallet's public keys.
Paste a sk_live_… key. Live keys and webhooks are separate from test ones: add the callback address again in live mode and paste its secret.
Add your WHMCS's https address to Sites that may embed the checkout in live mode.
Pay one small real invoice and refund it.