UTOPAY for WHMCS

What the module does

• Two buttons on the invoice: Pay by card / PayPal (4.5%) and Pay with crypto with a coin selector (1.5%). Either can be turned off.
• The client pays the invoice balance, so partly paid invoices work too.
• The payment is applied with addInvoicePayment only after the module re-reads it through the API: paid, same amount and currency. The UTOPAY payment id becomes the transaction id, so a payment is never applied twice.
• Invoices in a currency UTOPAY does not accept (for example RUB) are paid in the Convert To For Processing currency; the invoice is credited in its own currency.
• Nothing is called while an invoice is displayed: the payment is created only when the client presses a button.

Installation

1. Download the ZIP above and unpack it.
2. Upload the contents of the utopay-whmcs folder to the WHMCS root — the modules folder merges with yours: modules/gateways/utopay.php, modules/gateways/utopay/, modules/gateways/callback/utopay.php.
3. In the UTOPAY dashboard open Integration → API keys and create a test key utopay_sk_test_….
4. WHMCS admin → System Settings → Payment Gateways → All Payment Gateways → UTOPAY.
5. Paste the key, choose the payment options and save.
6. For crypto: add your EVM wallet in the dashboard (Project settings → Funds & payouts, section Crypto wallets) and list the coins in the module settings.

Settings

Test payment

1. With the test key, open an unpaid invoice in the client area and press Pay by card / PayPal.
2. The UTOPAY sandbox opens. Press the green ✅ button to simulate a payment.
3. You return to the invoice. Within a few seconds it becomes Paid; Billing → Gateway Log shows “Success” with the payment id.
4. Replace the key with utopay_sk_live_….

How invoices are confirmed

Each payment carries its own notification URL: /modules/gateways/callback/utopay.php with the invoice number and amounts, signed with a key derived from your secret key. UTOPAY signs every event (HMAC-SHA256) and retries for six hours if WHMCS does not answer 2xx.

The module checks both signatures, re-reads the payment through the API and applies it only when the payment is paid with exactly the requested amount and currency. Every step is written to the Gateway Log.

Troubleshooting

• “Invalid request token” — the invoice page was opened before the key was changed; reload the invoice.
• “amount is below the minimum” — the balance is below the minimum of the method or coin; the client can choose another one.
• The invoice stays Unpaid — WHMCS must be reachable from the internet and /modules/gateways/callback/ must not be blocked by a firewall or HTTP auth. Look at Billing → Gateway Log.
• Gateway Log: “Underpaid” — the client sent less crypto than required. The money is in your wallet: add a partial payment manually.
• “currency … is not supported” — set Convert To For Processing to USD or EUR.

Changelog

• 1.0.1 — shared UTOPAY core updated, no behaviour change.
• 1.0.0 — first release: cards & PayPal, crypto, Convert To For Processing, Russian buttons.

SHA-256: ab17e573fe3784fb5217c408d389a51af7196173d29f79d287938f9320a4327a

Updated October 11, 2026 · UTOPAY integrations team