WHMCS crypto payment gateway: how do I accept crypto payments in WHMCS?

Payzum is a non-custodial, stablecoin-first crypto payment processor: payments settle directly to wallets the merchant controls. Its WHMCS crypto payment gateway is an open-source module published at github.com/payzum-dev/whmcs-payzum. This guide is for hosting companies, domain resellers and anyone else who bills through WHMCS. It covers why hosts are adding stablecoins in 2026, six checks for any crypto module, and the Payzum module step by step. Then it covers what changes for renewals when the payment can't be charged automatically, and how the Blesta, HostBill and ClientExec modules differ. If you want the business case first, read accepting crypto payments as a web hosting provider. This post stays inside the billing system.

Why hosts are looking for a WHMCS crypto payment gateway in 2026

A popular crypto option disappeared this year. Coinbase closed its Coinbase Commerce merchant portal on 31 March 2026. Billing platforms had to follow. The Blesta 6 migration guide says it plainly: "Coinbase shut down the Coinbase Commerce service, so the gateway no longer functions." Blesta 6.0 removed the gateway, and WHMCS installs that took crypto through third-party Coinbase Commerce modules lost the option when the service closed. Hosts whose clients pay in crypto are now choosing a replacement.

Cards are expensive across borders. Hosts routinely bill clients in other countries. Take Stripe's published pricing for Spain, checked on 3 October 2026. A card issued outside the EEA costs 3.15% + €0.25, and currency conversion adds 2%. A €1,800 dedicated server billed to a client in Mexico, paid in dollars, costs €92.95 in fees. And each dispute costs €20 to receive and another €20 to fight, refunded only if you win.

Hosting attracts card fraud. A server is delivered in minutes, and a stolen card can be disputed for months. WHMCS's own documentation warns about it. Its credit settings note that letting clients add funds without an approved order "may increase the risk of chargebacks and fraud".

Some clients would rather pay in USDT anyway. Developers, crypto projects, game-server communities, and clients in countries where foreign cards are often declined. Without a stablecoin option they leave or pay late, and nobody earns from either.

What a weak crypto module costs a WHMCS install

Adding crypto doesn't remove risk by itself. Billing modules fail in ways that are specific to WHMCS, and each failure costs money or a support weekend:

• Invoices marked paid by the return page. If the module trusts the client coming back to viewinvoice.php, anyone can fake that visit. Crypto confirmation is asynchronous, and the browser is the wrong witness.
• Two checkouts for one invoice. A client refreshes the invoice page, gets a second deposit address and pays both. You now owe a refund and a support ticket.
• Credited for less than the invoice. A module that only checks the status, not the amount, marks the invoice paid off a smaller payment. That could be an old checkout raised before a credit was applied, or a forged one raised for a cent.
• The same payment credited twice. Payment providers retry callbacks. Without a duplicate check, each retry adds another payment to the invoice and the excess turns into client credit.
• A public callback that fills your database. A callback URL that logs every unsigned request in full lets anyone write megabytes into your gateway log, again and again.
• A module nobody maintains. A gateway written for WHMCS 7 and never updated breaks at the next PHP upgrade, which WHMCS 9 forces: it needs PHP 8.2 or later.
• Funds parked in someone else's balance. Custodial gateways collect your revenue in their own wallet and pay you out on their schedule, with their minimums and their freeze policy.

Why card gateways, bank transfer and custodial crypto fall short in hosting billing

Card gateways win on automation and lose on finality. WHMCS stores a card token and charges each renewal without the client lifting a finger. That convenience is real. But the money can come back long after the server was provisioned. The acquirer holds the funds first, and every dispute costs fees whether you win or lose.

Bank transfer is final but manual. The client wires the money, you match the transfer to an invoice by hand, and international wires take days and often arrive short of bank fees. Meanwhile the service waits, or runs unpaid.

Custodial crypto gateways fix acceptance but not custody. The client pays the gateway's address, the gateway credits a balance, and you withdraw when it allows. That balance is what a provider can freeze, or what you must move when it closes.

A bare wallet address skips everything else. Pasting an address on the invoice gives you no unique amount per invoice, no status, no underpayment detection and no automation. Someone ends up matching blockchain transactions to invoice numbers.

A hosting company needs a gateway that behaves like any other WHMCS payment method: an invoice marked paid, a transaction in the client's history, automation that runs. It should also settle like crypto: final, in seconds, to a wallet you control. For the finer points of hosting abuse on a final payment rail, see the hosting provider guide.

How to choose a WHMCS crypto payment gateway: six checks

Several crypto modules exist for WHMCS. Six questions separate one you can run in production from one you'll regret. Ask them of any vendor, including us:

1. Where do the funds settle? In your own wallet, or in a balance the provider holds and pays out later? Only the first leaves nobody able to freeze the money.
2. What marks the invoice paid? WHMCS's developer documentation defines a third-party gateway as one where "a customer leaves the site to pay and returns when the payment process is complete". Returning proves nothing. Look for a server-to-server callback whose signature is verified over the raw request bytes, with a replay window.
3. Is the amount checked, and in the right order? WHMCS's checkCbTransID rejects any transaction ID it has already seen. A module that records the transaction before checking the amount can't fix a bad credit later, because the corrected retry is refused as a duplicate. The amount check has to come first.
4. What happens on a refresh and on a retry? A refreshed invoice page should reuse the open checkout, and a retried callback should change nothing.
5. Does it fit your WHMCS and PHP versions? According to the WHMCS docs on 3 October 2026, 9.0 is in General Availability and needs PHP 8.2 or 8.3. 8.13 is the Long-Term Support release, and every earlier version is end of life. A module that predates PHP 8 is not an option.
6. Can you read the code, and what does it log? Open-source code lets your developer check how the callback is verified and where the money goes. Check that it doesn't write unsigned request bodies into your logs.

Our guide to open-source crypto payment plugins turns checks 2, 4 and 6 into a 15-minute audit you can run on any repository.

How Payzum's WHMCS module handles an invoice payment

The module is a standard WHMCS Third Party Gateway. It does two things: turn an unpaid invoice into a Payzum checkout, then let a signed callback, and nothing else, apply the payment.

On the invoice: one checkout per invoice

The client opens the invoice and clicks Pay with Crypto, or whatever your "pay now" text says. The module creates a Payzum invoice for the amount due in the invoice's currency. The amount travels as an exact string, so it isn't rounded on the way out. The client lands on Payzum's hosted checkout, with a QR code, a deposit address and a live status, and pays from any wallet without creating an account.

The module records that checkout in its own table, mod_payzum_payments, which it creates the first time it runs. If the client refreshes the invoice page, they get the same checkout while it is open for the same amount. If the amount due changes, for example because credit was applied, the old checkout is replaced. If the client has paid but the callback hasn't arrived yet, the page says "Crypto payment received — awaiting confirmation" instead of offering a second checkout. And if Payzum can't be reached, the page asks the client to try again shortly. It never guesses.

The module doesn't choose the coin. The checkout offers only the tokens you accept, which you set in your Payzum dashboard under Merchants → Settings → Accepted tokens, and Payzum enforces that list on its side. For most hosts that means USDC and USDT on fast, low-fee networks: Solana confirms in about 0.4 seconds, and Base and Polygon in about two. If you also accept other crypto, optional auto-convert to USDC or USDT is available on most supported networks.

After payment: the signed callback applies it

Payzum notifies modules/gateways/callback/payzum.php server to server. Before reading a single field, the callback verifies an HMAC-SHA-512 signature over the raw request bytes with your webhook secret. The comparison runs in constant time, and replays outside a 10-minute window are rejected. A bad signature gets a 401. The gateway log keeps only the size and a short hash of the rejected request, never its body.

Then come WHMCS's own checks. checkCbInvoiceID confirms the invoice number is valid. On a finished payment, the module compares the paid amount and currency with what it asked Payzum to charge, with half a cent of tolerance. A shortfall, a different currency or an unreadable amount is logged as "Not credited" with the full details, and the invoice is left alone. Only after that does checkCbTransID reject a payment ID it has already applied, so retries become no-ops. Finally, addInvoicePayment records the payment with the Payzum payment ID as the transaction ID and a zero fee. The money is already in your wallet, so there is nothing to deduct.

Every other status is written to the gateway log and changes nothing. That covers waiting, partially paid, expired and failed payments, plus late deposits and wrong-token alerts. The engineering behind this pattern is covered in signed webhooks for crypto payments. The HTTP client and signature check come from the official payzum/payzum-php SDK, which ships inside the module, so there's no Composer step.

What WHMCS does next

To WHMCS, a paid invoice is a paid invoice, whatever gateway paid it. Products set to set up automatically on payment are provisioned. A paid renewal invoice moves the service's next due date forward. And if Enable Unsuspension is on, a service suspended for non-payment comes back by itself. Your provisioning modules, emails and hooks run as they do today.

Where the money goes

Nowhere near Payzum. The client's payment goes from their wallet straight to the wallet set in your dashboard, and the module's code contains no wallet address at all. There is no Payzum balance to withdraw, freeze or wait for. The model is explained in what a non-custodial crypto payment processor is.

How to set up the WHMCS crypto payment gateway, step by step

Most of the time goes into the staging test, which is the step worth doing properly.

1. Check your stack. The module needs PHP 8.1 or later with ext-curl. WHMCS 9.x already requires PHP 8.2. On WHMCS 8.13, which runs on PHP 7.2 to 8.3, check which PHP your server actually uses. The callback must be reachable over HTTPS.
2. Set up your Payzum merchant account. Sign up at merchant.payzum.com. Add the wallet you want to be paid into and choose your accepted tokens, for example USDC on Base, Solana and Polygon, plus USDT. Create an API key under Developers → API keys and note your webhook (IPN) secret.
3. Install the module. Download payzum-whmcs-1.0.0.zip from the repository's Releases page and unzip it at your WHMCS root. The archive already mirrors modules/gateways/, including the bundled SDK. Don't use GitHub's green "Download ZIP" button: it unpacks to the wrong folder.
4. Activate it. Go to Configuration → System Settings → Payment Gateways and activate Payzum (Crypto & Stablecoins). Paste the API key and webhook secret, and set Environment to Staging for now. Staging has its own API keys; a production key won't work there.
5. Nothing to paste for the callback. The module sends https://<your-whmcs>/modules/gateways/callback/payzum.php with every checkout it creates. It must accept POST requests from the internet, so an install behind basic auth, an IP allowlist or a maintenance page will never hear back.
6. Test on staging. Create an invoice for a test client and pay it. Refresh the invoice page before paying: you should get the same checkout. After paying, the invoice turns Paid and the transaction shows the Payzum payment ID. Look at the gateway log for the Successful entry.
7. Go live. Switch Environment to Production, paste your production key and secret, and pay one small real invoice.

The gateway settings at a glance

There is deliberately no field for the signature header. The SDK fixes it, so nothing on this screen can drift out of sync with your account.

What happens in WHMCS at each payment status

Nothing in this table is triggered by the client's browser. A closed tab never loses a paid invoice, and a fake return visit never pays an unpaid one.

Renewals in WHMCS when the payment is crypto

This is the part to get right before you announce the option, because crypto renewals work differently from card renewals.

Why WHMCS can't charge crypto automatically

A card gateway can charge a stored token whenever WHMCS asks. A crypto payment is pushed by the client from their own wallet, and nobody can pull it. So the Payzum module stores no payment method. Each renewal is an invoice that the client pays, the same way they paid the first one.

The renewal cycle, step by step

1. WHMCS generates the renewal invoice. By default it does this 14 days before the service's next due date. You set this under Invoice Generation in the WHMCS automation settings, with different values per billing cycle if you want.
2. The client gets the invoice email and reminders. They open the invoice and pay in USDC or USDT. The service's payment method can stay set to Payzum, so the right button is there each time.
3. The callback marks it paid. The next due date moves forward one cycle, exactly as with any other gateway.
4. If the client is late, your usual overdue reminders and Suspend Days apply. Once they pay, Enable Unsuspension brings the service back automatically. It won't reactivate services you suspended by hand with a custom reason, such as an abuse case.

Prepaid credit: the closest thing to auto-renewal

WHMCS has a credit system that suits crypto well. Clients use Add Funds in the client area to top up their balance, and pay that deposit through Payzum. With Automatic Credit Use on, which is the default, WHMCS applies the balance to new renewal invoices as soon as it generates them. Note two details from the WHMCS credit documentation. First, credit isn't applied automatically to invoices that already exist when the client tops up; the client or an admin applies it to those. Second, clients can only add funds once they have an active, approved order. WHMCS recommends keeping that requirement on.

A client who tops up a year of hosting in USDT renews without thinking about it, and you hold the money from day one. Annual billing cycles reduce the number of payments in the same way.

Blesta, HostBill and ClientExec: the same model, platform by platform

The three sibling modules share the hosted checkout, the signed callback, the amount check and the bundled SDK. They differ in how each platform expects a gateway to behave.

Blesta

The Blesta module is a non-merchant gateway, so the client is redirected to pay and Blesta records the result from the signed callback. One payment can cover several open invoices at once. A finished payment is recorded as approved, an expired or failed one as declined, and one still in flight as pending. The client's return from the checkout is only ever recorded as pending. A finished payment that doesn't match the amount is recorded as declined, so a person looks at it before it touches the invoices. Set the IPN URL field to your gateway callback, https://your-blesta/callback/gw/{company_id}/payzum/, and enter the same URL in your Payzum webhook settings. Note that the module offers itself for five currencies only: USD, EUR, GBP, CAD and AUD. Blesta 6.0 requires PHP 8.2, and the module doesn't declare a Blesta version range, so test it on a staging copy of your exact version.

HostBill

The HostBill module refuses to rely on the platform to block duplicate transactions. It keeps its own small ledger of the amount each invoice was raised for and of every payment ID it has credited, so a retried callback credits nothing. Since its April 2026 update, HostBill itself requires PHP 8.1 to 8.3. The module's README is honest about one thing: HostBill's module API is proprietary, and the module follows its common pattern. Validate it on staging against your HostBill version before going live.

ClientExec

ClientExec 7.0 has been the stable release since 2 March 2026 and requires PHP 8.2 or later. Before anything else, set the plugin's Currency field if your installation doesn't define its own currency code. It has no default on purpose: the plugin won't invoice in a guessed currency. If the plugin can't book a payment, it logs an error and answers with a server error, so Payzum retries the delivery instead of losing it. As with HostBill, the README asks you to validate the redirect and the invoice credit on staging first.

What these modules don't do

• No automatic charging. Renewals are paid by the client, invoice by invoice or from prepaid credit. Keep your card gateway for clients who want hands-off renewals.
• Mismatches need a person. A short or wrong-currency payment is logged, not credited. You decide whether to refund the difference or apply the payment by hand. A partial payment waits until the client pays the rest.
• Refunds go out from your wallet. The modules don't push refunds. You send the stablecoins back yourself and record the refund in your billing system.
• The HostBill and ClientExec ledgers live in the server's temp folder. If that folder is wiped between the checkout and the payment, the amount check for that invoice falls back to a log entry instead of a block.
• Distribution. As of 3 October 2026, all four modules are distributed as GitHub releases. None is listed on the WHMCS Marketplace or another vendor store.

Use cases: hosting businesses taking USDC and USDT

The setup is the same for every host. What changes is which part of it pays for itself.

• VPS host in Finland with clients in the Americas. A small host bills a €240-a-year VPS to a developer in Brazil, who pays with a card in dollars. Stripe's published pricing in Finland comes to 3.15% + €0.25 plus 2% for conversion: €12.61. Six weeks later the card is reported stolen, the money goes back, and the dispute costs another €20 to receive. Paid in USDC on Base instead, the invoice is marked paid seconds after confirmation, the next due date moves on a year, and the payment can't be reversed.
• Domain reseller with prepaid clients. An agency manages 300 domains for clients in Argentina and Nigeria who would rather pay in USDT than with a card. Clients top up their WHMCS credit in USDT through Add Funds. Every renewal invoice WHMCS generates is paid from that balance the moment it's created, and no domain lapses because a card was declined.
• Blesta host that relied on Coinbase Commerce. A host in Canada took crypto through Coinbase Commerce until the service shut down on 31 March 2026, and the gateway is gone from Blesta 6. It installs the Payzum non-merchant gateway, tests one invoice on a staging copy, and offers crypto again. Existing clients, invoices and services stay exactly as they were.
• Game-server host with young, crypto-native clients. A Minecraft and Rust server host runs WHMCS with suspension after three overdue days. A client in Poland pays an overdue renewal in USDT on Solana on a Saturday night. With Enable Unsuspension on, the server is back before the client has closed the checkout tab, and nobody had to answer a ticket.

Payzum for WHMCS vs a card gateway, bank transfer and a custodial crypto gateway

Compared on neutral criteria. Card figures are Stripe's published pricing for Spain, checked on 3 October 2026.

A self-hosted crypto server is another fair option if you want no third party at all and have someone to run it. Payzum is for hosts that want the same custody without operating payment infrastructure. And you don't have to drop anything: most hosts add Payzum as one more gateway next to cards.

Common objections, answered

"Our clients will lose auto-renewal."

Only the ones who choose crypto, and they know they're pushing payments from a wallet. Keep your card gateway for everyone else. For crypto clients, prepaid credit and annual cycles turn renewals into a non-event. Your reminder emails and grace period do the rest.

"Won't crypto attract abusers?"

A final payment removes chargeback fraud, and it also removes the card issuer's decline as a fraud filter. Your signup screening and abuse desk matter more on this rail, not less. We cover that trade-off honestly in the hosting provider guide. WHMCS's own controls still apply, including the rule that clients can only add funds after an approved order.

"What about volatility?"

Your prices stay in your billing currency. The module sends the invoice total in the invoice's currency, and the client pays the equivalent in the coin they choose. Accept only USDC and USDT and you receive dollar stablecoins. If you accept other crypto too, optional auto-convert to USDC or USDT is available on most supported networks. USDT vs USDC for payments helps you choose.

"I don't install payment code I can't read."

Good, and you don't have to. The WHMCS module is two PHP files plus the bundled official SDK, all public under MIT. It stores no card data and no wallet address. It sends Payzum only the invoice number, amount and currency, and your callback and return URLs. The callback rejects unsigned requests before it reads anything.