Build a WHMCS Custom Payment Gateway for Crypto Billing

You do not actually need “a custom WHMCS payment gateway.” You need the right payment lifecycle inside WHMCS for the billing model you run.

That sounds like semantics until a team ships a module that renders a pay button, creates a checkout link, marks the first invoice paid, and then falls apart on month two. Renewals stall. Duplicate callbacks create a mess. A crypto checkout flow gets labeled “subscription” even though customers still have to come back and pay by hand.

This guide is for the moment before that mistake hardens into production. If you are choosing whether to build a WHMCS custom payment gateway For crypto billing, the order matters: pick the gateway pattern first, define the recurring model second, then write the module around that. Anything else won’t hold.

Quick answer: what a WHMCS custom payment gateway really is, and when to build one

A custom WHMCS payment gateway is a PHP module that lets WHMCS work with a payment provider or billing rail it does not support well out of the box. That might be a card processor, a regional method, a hosted checkout flow, or a crypto billing backend.

You build one when the gateway layer is blocking the business. Maybe there is no stable marketplace module for your provider. Maybe the plugin exists, but recurring logic is thin, refunds are manual, or webhook handling is sloppy. Maybe you are in a high-risk category and standard processors freeze accounts, reject onboarding, or make every renewal feel temporary. Maybe you want self-custodial crypto billing that settles to your wallet instead of routing money through another middleman.

Do not build a custom module for sport.

If a maintained module already supports your exact flow, renewals, refunds, and callback states, use it. Custom work makes sense when the existing options force ugly compromises: manual monthly payment chasing, broken invoice states, weak recurring support, or a custody model you do not want attached to your revenue.

The first choice that decides everything: which WHMCS gateway type are you actually building?

WHMCS documentation explains the categories. What it does not make clear enough is how expensive the wrong category becomes later. Many “payment bugs” are architecture mistakes wearing a different name.

Start here.

Gateway pattern	Best use case	Customer flow	Recurring model	Webhook dependency	Crypto fit	Typical complexity
Merchant / direct API	Traditional card or bank API where your server initiates charges	Usually onsite or embedded	Stored token or provider charge API	Medium	Weak	High
Third-party / hosted checkout	Offsite payment page, redirect flow, wallet checkout	User leaves WHMCS and returns later	Provider-managed or external commitment	High	Strong	Medium
Tokenization	Saved cards, vaulted payment methods, repeat billing	Fast repeat billing	Card token or mandate	Medium	Poor fit for native crypto	High
Manual / async settlement	Bank transfer, reviewed invoices, delayed confirmation	Customer pays outside immediate checkout	Usually none	Optional to high	Limited	Low to medium

For most crypto payment flows, the practical fit is third-party or async. Even when the business says “subscriptions,” the underlying shape is rarely the same as card tokenization. That mismatch is where teams talk themselves into trouble.

Common scenarios mapped to the right gateway pattern

If you are integrating an unsupported card processor with proper token storage and charge APIs, you are usually building a merchant or tokenization-style module. If the provider owns the payment UI and returns status later, treat it as a third-party gateway and let webhooks carry the real truth.

If you are adding one-time crypto invoice payments, again, third-party or async is usually the cleanest fit. The customer pays offsite or through a wallet action, your callback receives confirmation, and WHMCS updates the invoice. That is straightforward enough.

True recurring crypto billing is different. The problem is no longer “how do I collect this invoice?” It becomes “what authorizes month two, month six, and month twelve without dragging the customer back through a fresh payment flow every time?”

That is a different class of system.

Most guides start with module files. In practice, recurring logic should decide your design first

The PHP files are the easy part. The renewal model is where your gateway either becomes a durable billing system or a polite future headache.

A lot of WHMCS gateway development Guides jump straight into /modules/gateways/yourgateway.php. Fine. But if you have not decided how future invoices will actually be collected, you are building a demo, not a payment system.

This is where almost everyone loses.

Card-based recurring billing usually rests on a token, vault reference, or mandate. A non-custodial crypto subscription usually rests on a prior wallet approval or on-chain commitment. A one-time payment link has none of that. So if your WHMCS custom payment gateway only generates a crypto checkout URL per invoice, you do not have recurring billing. You have monthly collection risk wrapped in a cleaner interface.

The cost shows up late, which makes it dangerous. The first invoice succeeds, everyone relaxes, and then renewals depend on customers noticing invoice emails, returning on time, holding the right balance, approving again, and caring enough to repeat the ritual every month. Churn rarely arrives with drama. It leaks through open invoices, quiet cancellations, and support tickets that should never have existed.

WHMCS module anatomy: the files, functions, and responsibilities

Once the billing model is clear, the module itself becomes much easier to reason about. A typical custom WHMCS payment gateway centers on two files:

/modules/gateways/yourgateway.php Handles the gateway definition, admin config, payment UI, and core actions. /modules/gateways/callback/yourgateway.php Handles webhook or callback events from the provider.

Hooks usually live in the hooks directory and should be kept for orchestration, renewal glue, or status sync. They should not become your hidden payment engine. When payment truth is smeared across hooks, templates, and callback files, maintenance turns ugly fast.

Component	Purpose	Usually required?	Common mistake	2026 guidance
Yourgateway_config()	Defines admin-visible settings	Yes	Stuffing runtime logic into config definitions	Keep credentials, mode, API base URL, webhook secret, display label
Yourgateway_link()	Renders payment button or starts checkout flow	Common for offsite flows	Embedding too much client-side state and skipping server-side references	Create the external payment object server-side and map invoice IDs safely
_capture()	Direct capture for merchant-style flows	Only for suitable gateway types	Forcing async crypto flows into card-style capture semantics	Do not bend crypto into a card-shaped API if the provider model does not match
_refund()	Sync refunds back to the provider	Optional but valuable	Logging a refund in WHMCS without actually executing it provider-side	Only expose refund support if the backend can perform it reliably
Callback file	Receives provider events	Yes for async flows	Treating query params or browser returns as proof of payment	Verify signatures, amounts, currencies, event IDs, and idempotency every time
Hooks	Renewal sync, payment method handling, lifecycle glue	Often	Letting hooks become the main source of billing truth	Use hooks to coordinate, not to settle money

Minimal module skeleton for a modern offsite or API-backed gateway

The exact function set can vary by WHMCS version and gateway type, so verify signatures against the current developer docs before shipping. Still, the shape below is the right mental model for a WHMCS payment module That keeps recurring crypto logic in an external backend.

<?php

if (!defined("WHMCS")) {
 die("This file cannot be accessed directly");
}

function yourgateway_config()
{
 return [
 "FriendlyName" => [
 "Type" => "System",
 "Value" => "Your Gateway"
 ],
 "apiKey" => [
 "FriendlyName" => "API Key",
 "Type" => "text",
 "Size" => "60",
 ],
 "webhookSecret" => [
 "FriendlyName" => "Webhook Secret",
 "Type" => "password",
 "Size" => "60",
 ],
 "testMode" => [
 "FriendlyName" => "Test Mode",
 "Type" => "yesno",
 "Description" => "Enable sandbox mode",
 ],
 ];
}

function yourgateway_link($params)
{
 $invoiceId = $params["invoiceid"];
 $amount = $params["amount"];
 $currency = $params["currency"];

 // 1. Create external checkout/subscription session via your backend API
 // 2. Store external reference against invoice or transaction metadata
 // 3. Return payment button / redirect link

 return '<a href="#">Pay with Crypto</a>';
}

The important part is not the button. It is the reference model behind it.

Every payment attempt should create or reuse a stable external object with a clear mapping to invoice ID, customer reference, amount, currency, and an idempotency key. That mapping is what saves you when callbacks arrive twice, return out of order, or disagree with what the browser told the user.

End-to-end payment lifecycle inside WHMCS: where state changes happen

A good gateway is not a checkout widget. It is a state machine with money attached.

Before you write production logic, map the full payment lifecycle from invoice creation through settlement. WHMCS renders an invoice. Your module creates a checkout session, wallet approval request, or subscription intent. The customer completes an external step. The provider sends a server-to-server event. Your callback validates it, matches it to the right invoice, and records the transaction once.

That “once” matters more than people think.

Step	WHMCS component	Provider/API event	Main risk	Recommended handling
Invoice created or displayed	Invoice page, gateway selection	None yet	Wrong amount/currency assumptions	Use invoice values as source data and send them explicitly to provider
Payment initiated	Yourgateway_link() Or equivalent flow	Create checkout or subscription object	Missing external reference mapping	Store a stable provider reference and your own idempotency key
Customer completes external step	Return URL for UX only	Redirect, wallet approval, hosted checkout return	Treating browser return as payment success	Show pending or processing state until webhook confirms
Provider confirms payment	Callback file	Payment.completed Or equivalent	Replay, forged webhook, duplicate application	Verify signature, validate amount and currency, enforce idempotency
Invoice marked paid	Invoice transaction handling	Validated final event	Duplicate transaction records	Record transaction once and reject stale or repeated events
Renewal or refund event	Hooks, invoice state, transaction history	Renewal success/failure, refund/cancel event	State drift between WHMCS and provider	Define ownership of schedule, retries, cancellations, and refund sync up front

Most production failures happen in the gap between customer-visible actions and server-side truth. The user returns before the webhook lands. Or the webhook lands first, marks the invoice paid, and then a stale browser return tries to settle it again. Or the provider retries the same event and your callback happily books it twice.

Use the server callback as the source of truth for async and crypto payments. The browser return is just UX.

Recurring billing in WHMCS is not one thing: the four models you need to separate

Teams often ask, “Can a custom WHMCS gateway support recurring billing?” Yes. But that answer is almost useless until you define what “recurring” means in your architecture.

There are four common models: stored card token, provider-managed subscription object, mandate or billing agreement, and on-chain commitment or wallet approval. WHMCS can sit on top of any of these. It does not erase the differences between them. If you do not know which system owns billing dates, retries, cancellations, and payment truth, you are already building on sand.

Why invoice-by-invoice crypto is not the same as subscription billing

Here is the distinction that matters in real operations. A hosting reseller adds a crypto plugin that generates a fresh payment request for every invoice. Customers can pay in USDT. Invoices close. For a while, it looks good.

Three months later, the cracks show. Some customers miss the invoice email. Others open it late and hit an expired quote. Some pay from the wrong wallet. Some intend to renew and simply never get around to it. Nothing is technically broken. The model is broken.

Now compare that with a platform selling API access globally, where some customers cannot or will not use cards. The customer approves once through a wallet flow, future monthly USDC collections happen under that approval, and renewals behave like renewals instead of recurring reminders.

That gap changes the business. Retention lives there.

Building a crypto gateway for WHMCS: the model is different because there is no card token

With card gateways, the recurring anchor is usually a token, vaulted method, or mandate. With crypto billing, especially non-custodial billing, the recurring anchor is often an on-chain approval or commitment that allows future collections inside agreed limits.

That difference matters because many teams try to force crypto into the mental model of a card processor. The result is usually clumsy. There is no native card-style token unless a custodian creates one for you, and that often brings the very baggage merchants were trying to escape: custody risk, KYC overhead, platform dependence, and account fragility.

A practical Custom WHMCS gateway For crypto billing usually starts with stablecoins rather than volatile assets. It keeps invoice amount and settlement currency mapping explicit. It defines when a payment counts as final, how expired payment windows behave, and what happens with underpayment or overpayment before launch instead of during a support incident.

Write those rules early.

If self-custody is part of the reason you are doing this, settlement should flow directly to the merchant wallet. If refunds are supported, the provider-side and WHMCS-side behavior must stay in sync. If renewals depend on a prior approval, your module needs a clean way to track that relationship without pretending it is a saved card.

This is the trap to avoid: if your crypto “subscription” still asks the customer to manually approve a fresh payment every month, you did not build subscriptions. You built one-time checkout for a recurring business. Different label. Same weakness.

0.5% platform fee vs 2.9% + 30¢ card economics: where custom crypto billing changes the math

For merchants charging $5 to $500 per month, payment economics are operational, not theoretical. Card processors commonly land around 2.9% + 30¢ and bring chargeback exposure with them. On small subscriptions, the fixed fee hurts. On larger plans, percentage drag stacks up fast.

Zyrox is positioned as a non-custodial recurring crypto backend with a 0.5% platform fee, direct settlement to the merchant wallet, and no card chargeback layer. That does not remove your own merchant-side compliance obligations, and it does not make every business a fit. But for teams already dealing with frozen accounts, category bias, or margins chewed up by processor fees, the rail starts to matter a lot.

And when this works, the upside is bigger than lower fees. A well-built billing rail becomes a real asset: one approval model, global reach, direct wallet settlement, recurring revenue that does not depend on the next processor review, and a payment layer you can reuse across hosting, SaaS, API plans, or creator subscriptions. That is worth building toward.

Tutorial path: build a minimal WHMCS custom payment gateway for crypto billing

The safest pattern is usually to keep the WHMCS layer thin and let a backend payment service own the subscription engine, payment object creation, and event delivery. That gives you a cleaner boundary. WHMCS owns invoices, account context, and admin behavior. The payment backend owns wallet approval, recurring collections, and settlement truth.

A minimal build path looks like this. Define gateway config in Yourgateway_config() With API credentials, sandbox mode, webhook secret, and display settings. In Yourgateway_link()Collect invoice ID, amount, currency, customer references, and return URL data. Call your backend API to create a checkout or subscription object. Store the external reference safely. Redirect the user into the wallet approval or hosted flow. Then let webhook receipt handle payment confirmation and invoice settlement.

Two shortcuts keep breaking real projects: trusting the customer return URL and assuming recurring becomes automatic after first payment. Neither survives production for long.

Creating the payment or subscription object from WHMCS invoice context

When you send data from WHMCS to the payment backend, keep the payload boring. Boring is good here. Include the WHMCS invoice ID, internal client ID or reference, amount due, currency, product or service context if needed, and a return URL for the user experience. Add a webhook correlation value and your own idempotency key.

If the invoice is one-time, create a one-time payment intent. If the service should renew, create a subscription or approval object that can support future billing events. Do not fake subscriptions by recreating one-time intents at every renewal unless manual repayment is a conscious business decision. For most recurring businesses, it is the wrong one.

One team we worked with had no trouble generating crypto checkout links. The first invoice looked perfect. Customers paid, WHMCS updated, everyone moved on. The break came later. Renewals had no reusable approval behind them, so every month depended on the customer coming back and paying manually again. Nothing crashed. Revenue just leaked through open invoices and support tickets asking why “autopay” was not actually autopay.

That kind of failure is nasty because it hides behind initial success. Fresh paint over a cracked wall.

Webhooks and callbacks: how to mark invoices paid without creating accounting chaos

If you tighten one part of your WHMCS gateway development Process, tighten this one. Weak webhook handling is how an innocent module turns into duplicate payments, missed settlements, and messy reconciliation.

Your callback should verify the webhook signature or HMAC before trusting the payload. It should confirm the invoice or subscription exists. It should validate amount, currency, and provider status against what you expected. It should enforce idempotency so replayed events do not apply payment twice. And it should log enough to debug without dumping secrets into logs or exposing sensitive payloads to the wrong place.

Then comes the harder part: state discipline. A completed payment event can settle an invoice. A pending event should not. A failed renewal may need customer messaging or admin visibility, but it should not mutate historical transactions. Out-of-order delivery happens. Your callback has to recognize stale transitions and ignore them.

Customer return URL vs server webhook: which signal should actually finalize payment?

Use the webhook.

The customer return URL is useful for reassurance: “thanks, we received your wallet action” or “payment is processing.” It is not strong enough to settle accounting. Browser returns can be abandoned, repeated, spoofed, or arrive before the payment reaches finality. In crypto flows, they can also arrive while confirmations are still pending.

Webhook-first logic feels less satisfying in local testing because you want the instant green checkmark. Ignore that instinct. Browser-first accounting is how race conditions become finance problems.

Testing before launch: the cases that catch most broken WHMCS gateways

Most modules pass the happy path. That proves very little.

You need WHMCS test mode, a provider sandbox or test environment where possible, and replayable webhook testing. Run the cases that look like real merchant pain: successful first payment, duplicate webhook delivery, customer return before webhook arrival, expired payment session, underpayment, overpayment, failed renewal, canceled subscription, and refund handling if your module exposes refunds.

Scenario	Expected WHMCS result	Required validation	Common bug
Successful first payment	Invoice marked paid once	Signature, amount, currency, transaction reference	Relying on return URL instead of webhook
Duplicate webhook replay	No duplicate transaction recorded	Idempotency and unique event handling	Applying the same payment twice
Webhook arrives after browser return	Invoice stays pending until final confirmation	Pending UX state, webhook-first settlement logic	Prematurely marking invoice paid
Expired payment window	Invoice remains unpaid or returns to payable state	Status mapping for expired sessions	Leaving stale checkout links active
Underpayment or overpayment	Handled according to defined policy	Amount comparison and exception flow	Blindly accepting mismatched amounts
Failed renewal	Invoice remains due and status sync is clear	Renewal ownership and retry behavior	Assuming provider retries match WHMCS expectations
Refund event	WHMCS and provider stay consistent	Provider-side execution and local sync	Refunding in one system only

One small implementation team inherited a gateway that technically processed payments, but every WHMCS upgrade triggered a manual audit of hooks, callback assumptions, and invoice state logic. They were not dealing with one giant bug. They were paying interest on weak boundaries. Small team. Constant anxiety. Every release treated like a minefield.

That is the real maintenance bill.

Plan for WHMCS version movement, provider API drift, secret rotation, logging hygiene, and a clear list of which hooks and functions your module depends on. If a new developer cannot understand your payment lifecycle in one page, your future upgrades will be slower and riskier than they need to be.

Publishing on the WHMCS Marketplace: when it helps, and when private deployment is smarter

If your module solves a broad problem and can support different merchant setups, the WHMCS Marketplace may be worth the review process and visibility. It can also become a support commitment very quickly. Once a module is public, compatibility expectations rise, release timing matters more, and your support load can grow faster than the code matures.

For agency work or merchant-specific integrations, private deployment is often the better call. If the gateway depends on one backend, one renewal model, or one high-risk operating context, marketplace visibility can attract the wrong users and the wrong assumptions.

Ask a blunt question before you publish: are you shipping a reusable product, or a specific integration?

The answer should decide the channel.

Maintenance reality: your custom gateway is not done when payments work

A gateway that takes money today is only halfway built. The long tail is where most teams underestimate the job.

WHMCS major versions change. Provider APIs change. Payload fields drift. Admin paths move. Secrets need rotation. Logging rules get tightened. Callback assumptions that looked harmless during launch become brittle a year later. If your module depends on undocumented quirks or scattered hook behavior, every upgrade will feel like defusing a bomb with half the manual missing.

This is one reason thin modules age better. The less payment logic you bury inside the WHMCS layer, the fewer moving parts you have to re-audit every time the platform or provider changes. Clean boundaries buy time. Dirty ones compound maintenance forever.

Build from scratch, adapt a marketplace module, or use a backend payment primitive?

This is the decision-stage comparison that actually matters.

Build from scratch If you need total control, have the engineering depth to own recurring logic and webhook hardening, and expect the gateway to become a strategic internal asset. The upside is control. The downside is that you now own renewals, retries, callback reliability, API drift, settlement logic, and edge cases for as long as the business uses that rail.

Adapt a marketplace module If the fit is close and your needs are simple. It is faster up front. The trouble is that many crypto plugins stop at one-time checkout. They can look fine until you need reliable recurring behavior, cancellation sync, direct wallet settlement, or a non-custodial flow. Then you are editing someone else’s architecture in the dark.

Use a backend payment primitive If the WHMCS module is not the part you want to spend your time on. For recurring crypto billing, this is often the sharpest option. Keep the WHMCS layer thin. Let the backend handle wallet approval, future collections, payment state, and webhook delivery. Fewer moving parts in the module means fewer brittle points when WHMCS changes.

Many teams skip this trade-off because “full custom” sounds more independent. But raw ownership is not the same as useful control. If your team ends up maintaining a fragile recurring engine it never wanted to own, that is not freedom. It is debt.

If your goal is non-custodial recurring crypto billing, the hard part is not the WHMCS UI layer

By now the likely conclusion is pretty clear: yes, you can build a WHMCS custom payment gateway. A capable PHP developer can wire config, invoice context, payment links, callbacks, and state transitions. That is real work, but it is not the deepest risk.

The harder layer is the recurring crypto primitive underneath. Generic options usually fail in one of three ways: they are custodial, they only support one-time payments, or they drag in KYC and operational overhead that defeats the reason many merchants looked at crypto billing in the first place. If the customer has to come back every month and pay manually, you do not have subscription infrastructure. You have a reminder system with nicer branding.

Building that backend yourself means owning the wallet approval flow, monthly USDC pull logic, webhook reliability, settlement behavior, cancellation handling, retries, and event ordering. You can do that. But unless payment infrastructure is part of your product, it is a big forever decision.

That is where Zyrox Makes sense as a backend layer rather than as a generic payment pitch. It is positioned for non-custodial subscription billing: customers approve once via wallet, smart contracts handle monthly USDC collection, funds settle directly to the merchant wallet, and the platform fee is 0.5%. For the team building the WHMCS side, that changes the scope of the project. You keep the module focused on invoice integration, account context, and payment-state mapping instead of inventing the recurring crypto rail from zero.

If that is your use case, the next step is simple and earned: evaluate the backend before you finalize the module design. Start at App.zyrox.io If you are ready to test the product path. If you want the broader implementation view first, read the WHMCS Crypto Payment Gateway: Setup Guide 2026. Then scope the module around a real recurring engine instead of hoping one appears later.

What to do next while the architecture is still cheap to change

Before you write another line of gateway code, answer four questions on paper: which gateway pattern are you building, which system owns recurring logic, which event finalizes payment, and what happens on renewal failure. If those answers are fuzzy, stop and fix the design first.

That pause is not delay. It is leverage.

The teams that get this right end up with more than a working module. They get billing independence, lower processor risk, cleaner renewals, and a payment layer they can expand across products, regions, and customer segments. That is a real asset.

So make the next move count: choose the recurring model, choose the backend, then build the WHMCS layer around that truth. If you want to see the implementation path in context, read the WHMCS Crypto Payment Gateway: Setup Guide 2026. If you are ready to validate the product route, go straight to App.zyrox.io And test the recurring engine before you commit your module architecture to the wrong assumptions.

Frequently asked questions

Related articles

• WHMCS Crypto Payment: Which Gateway Fits Hosting Best?

  Complete 2026 guide to adding crypto payments to WHMCS — modules compared, step-by-step Zyrox install, recurring USDC for hosting.

• WHMCS USDC Subscriptions Without Chargebacks or Fee Shock

  Use USDC for recurring hosting subscriptions in WHMCS — predictable billing, no card chargebacks, lower fees. Setup guide for 2026.

• WHMCS Bitcoin Payment Gateway for Hosting: What Actually Works

  How to accept Bitcoin in WHMCS in 2026 — modules, Lightning support, recurring BTC billing limitations, and practical alternatives.

• Best Payment Gateway for WHMCS: 8 Options Compared

  Honest 2026 comparison of payment gateways for WHMCS — Stripe, PayPal, crypto options, multi-currency. Pick the right one for your hosting business.