WHMCS Payment Gateway Integration

What kinds of WHMCS payment gateway can be integrated?

WHMCS gateways fall into three designs, and the design decides how card data is handled and how renewals work. I pick the design before writing any code.

I steer almost every project to the first two designs. The third one pulls your server into much heavier compliance work, and I do not write code that stores card numbers.

Which files make up a WHMCS gateway module?

A gateway module is one main file plus one callback file. The main file is modules/gateways/<name>.php and the callback file is modules/gateways/callback/<name>.php, both using the same lowercase module name.

The main file defines <name>_MetaData() and <name>_config(), which draw the admin settings such as API keys and a test mode switch. A hosted gateway adds <name>_link($params), which returns the pay button or redirect shown on the invoice. A tokenized gateway adds <name>_capture($params) to charge a stored token, and <name>_refund($params) handles refunds. The callback file is a plain endpoint that the gateway calls over HTTPS, and it is where the money logic lives.

How does a callback mark an invoice as paid?

A callback marks an invoice as paid by running a fixed sequence of WHMCS helper functions, after the payment has been verified. The order matters, because each step guards the next.

1. getGatewayVariables() loads the module's saved settings, which the callback uses to confirm the gateway is active.
2. Verify the signature on the raw request body before trusting any field in it.
3. checkCbInvoiceID() confirms the invoice exists in this WHMCS.
4. checkCbTransID() stops processing if this transaction ID was already recorded.
5. logTransaction() writes the raw data and result to the gateway log, which is where I look first when a payment looks wrong.
6. addInvoicePayment() records the payment and fee against the invoice and marks it paid once the balance reaches zero.

I also compare the paid amount with the invoice balance before step six, so a partial or tampered amount is logged instead of being treated as full payment.

How do I stop forged and duplicate webhooks?

Verify the cryptographic signature on every request and record each transaction only once. A callback URL is public, so anyone can send it a fake "paid" message unless the signature is checked.

• Stripe signs each webhook in a Stripe-Signature header and includes a timestamp, so I also reject notifications that are too old.
• Razorpay sends an HMAC signature of the request body in an X-Razorpay-Signature header, checked against your webhook secret.
• PayPal webhooks are verified by sending the received headers and body back to PayPal's verification API.
• NowPayments signs its instant payment notifications with a secret key that I check on every call.

I compare signatures with hash_equals(), which avoids timing leaks. For duplicates, gateways retry notifications, so the same event can arrive twice or out of order. checkCbTransID() stops a second payment from being recorded, and for events that carry no transaction ID I store the gateway's event ID and ignore repeats. A duplicate still gets a quick success response, so the gateway stops retrying.

How do refunds work?

A refund started from the WHMCS admin area calls the module's refund function, which asks the gateway to return the money and reports the result back. The function returns a status of success, declined or error, plus the gateway's reference.

The harder case is a refund made in the gateway's own dashboard. WHMCS knows nothing about it unless the gateway sends a webhook and the callback handles it, so the invoice would still show as paid. I handle refund events in the callback where the gateway offers them, and I list in the handover notes any case, such as crypto, where the refund stays manual.

What about 3-D Secure and strong customer authentication?

For hosted and redirect gateways, the gateway runs the 3-D Secure challenge itself, so WHMCS has nothing extra to do. The difficult case is a renewal charged on a stored token, because the customer's bank may still demand authentication.

When a charge needs authentication, the module must treat it as a failed attempt, not retry blindly. I record the failure, let WHMCS send its normal payment reminder, and make sure the customer can open the invoice and complete the challenge on a hosted page. This matters most for customers in regions with strong customer authentication rules, such as the EU and UK.

How do currencies and gateway fees work?

WHMCS bills each client in their own currency, and many gateways accept only some. The admin gateway settings let WHMCS convert the invoice to a currency the gateway supports, and I make the callback read the converted amount.

Fees are recorded in the payment so your reports show net income. Some gateways send the fee with the notification, while others expose it only through a separate lookup after settlement. I record the fee when it is available and leave it empty when it is not, and I write down which case applies to your gateway.

How do you test a gateway before going live?

I test in the gateway's sandbox against a staging WHMCS that the internet can reach, because webhooks cannot be tested against a laptop. A public staging address or a tunnel makes that possible.

The test list covers a successful payment, a decline, an expired session, the same webhook sent twice, a late webhook, a partial amount, a currency conversion and a refund. After each case I check the invoice, the gateway log and the gateway dashboard, and they must tell the same story. Only then do I switch to live keys, take one small real payment and refund it.

Which gateways have you integrated?

For the Stripe and Razorpay setups I use most, the step-by-step notes are in WHMCS Stripe integration and WHMCS Razorpay integration.

I work with Stripe, PayPal, Razorpay and NowPayments, and with regional gateways that publish an API reference and a sandbox. WHMCS ships modules for several large gateways, and when one of those already does what you need, I will tell you to use it instead of paying for custom work. I build when the bundled module lacks a feature, such as a local payment method, or when the gateway has no module at all. A new module is a form of custom module development, and a gateway that touches payments is a natural place for a security review.

What will a gateway module of mine never do?

I will not store card numbers or security codes, and I will not build against a gateway that offers no documentation or sandbox. I cannot get a merchant account approved for you, since gateways make that decision. I do not edit WHMCS core files or work from cracked gateway modules. For crypto, price movement and confirmation rules are business decisions that stay with you. If you are setting up from scratch, WHMCS installation and setup includes connecting a gateway in sandbox mode.