Payment gateway modules allow you to accept payments of many types directly within WHMCS.
You can access this feature at Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways.
- 1 Activating a Payment Gateway
- 2 Setting Up Gateway Modules
- 3 Supported Gateway Modules
- 4 Deactivating Gateway Modules
- 5 Test Credit Card Numbers
- 6 Troubleshooting
Activating a Payment Gateway
To activate a new payment gateway:
- Find the payment gateway:
- In WHMCS 8.6 and later, go to Configuration () > Apps & Integrations.
- In WHMCS 8.0 to 8.6, go to Configuration () > System Settings > Payment Gateways.
- In WHMCS 7.10 and earlier, go to Setup > Payments > Payment Gateways.
- Click Activate.
- Configure the payment gateway (see below).
Setting Up Gateway Modules
Each gateway has its own specific API requirements in order to process transactions, which vary from gateway to gateway. However, all gateways have three core options:
- Show on Order Form — Whether to display the payment gateway on the order form and client area, subject to product group gateway restrictions. Also controls adding new payment details via the Admin Area for merchant gateways.
- Visible Name — The gateway's name throughout the system and to clients (for example, an Authorize.net gateway could use the visible name Credit Card).
- Convert To For Processing — When using multiple gateways, some gateways may not accept all the currencies you offer on your site. For those that don’t, you can choose a currency here for WHMCS to convert to before sending to them.
- For example, if using Google Checkout with a UK account but offering prices in GBP and USD, you would need to select GBP for Convert To. This will use the rates in Configuration () > System Settings > Currencies or, prior to WHMCS 8.0, Setup > Payments > Currencies, to do the conversion. You can set this to auto-update daily.
- For more information, see Converting Invoices to a New Currency.
Supported Gateway Modules
WHMCS includes the following payment gateways by default:
- Merchant Gateways store credit card information securely in the WHMCS database.
- Third-Party Gateways direct the client to the provider's website to process payments off-site.
- Tokenisation Gateways reduce PCI liabilities when they perform repeat billing by storing the original transaction details or a reference number and not the full credit card number. For more information, see Working with Tokenization.
Remote Update Card
For tokenisation gateways with the Remote Update Card feature, clients can enter their card details via the WHMCS Client Area. This is done via an interface that the payment gateway hosts directly or by paying an invoice. This creates a profile in the payment gateway's system that returns a token.
WHMCS uses this to manage the card detail update requests via the Client Area and recurring payments. This does not store the full card details on your server, and some token gateways never touch it.
The type of payment gateway that you select influences which invoice notification email template it sends.
Third-party gateways will send the Invoice Created email template, while merchant and tokenisation gateways will send the Credit Card Invoice Created email template. This allows you to customise the payment instructions to clients for the different payment processes.
The type of payment gateway also influences the behaviour when you click Attempt Capture on the invoice page in the Admin Area.
- For third-party gateways, the system will deactivate the button because the client needs to click the payment button on the invoice to send payment.
- For merchant gateways and tokenisation gateways, the button will be active and staff can click Attempt Capture to instantly capture payment from the client's credit card.
Any gateways showing in blue below indicate that further information relating to the setup and use of that gateway is available by clicking on the name.
Tokenisation gateways store a token to use for processing credit card payments through the merchant gateway module. The system won't add the token to WHMCS until someone has submitted a payment through the module. The system will store the credit card details in the database directly until the client makes a payment on an invoice through one of the token type gateway modules. After the payment is complete, the system fetches the token and replaces the credit card details in the database. Storage of the credit card details can also happen when the client updates their credit card details or when they place an order and the system does not process the payment immediately.
If you use a mix of both tokenized and non-tokenized payment gateways, customers can choose the desired payment method when adding one via the Client Area. This determines whether to store the card locally encrypted in the WHMCS database or remotely with the tokenized payment gateway.
|Accept.js by Authorize.net||Authorize.net CIM||Bluepay Remote|
|EWAY Rapid 3.1||Moneris Vault||PayPal Pro Reference Payments|
|Quantum Vault||SagePay Tokens||Stripe|
|Stripe ACH||Stripe SEPA||WorldPay FuturePay|
Third Party Gateways
You can create your own gateway modules for WHMCS if you want to integrate with a gateway that WHMCS doesn't offer by default.
For more information, see our Developer Documentation.
Deactivating Gateway Modules
When you stop using a payment gateway, make certain to deactivate it. Deactivation prevents new payments using this gateway and will automatically reassign any products, services, invoices, transactions, and pay methods to the new payment gateway.
To deactivate a payment gateway, click Deactivate. The system will prompt you to select an alternative payment gateway.
Change any currently-assigned items to this gateway.
Migrating Payment Gateways
For instructions to stop using one payment gateway and switch to another, see Migrating Payment Gateways.
Test Credit Card Numbers
Gateways often have test modes where you can use test card numbers. The common test card numbers are below and should generate successful test transactions, but they can vary from gateway to gateway. You may use any expiration date in the future:
4007000000027 - Visa Test Card 4012888818888 - Visa Test Card II 4000000000000002 - Visa Test Card III 5424000000000015 - MasterCard Test Card 370000000000002 - American Express Test Card 6011000000000012 - Discover Test Card 3088000000000017 - JCB Test Card (Use expiration date 0905) 38000000000006 - Diners Club/Carte Blanche Test (Use expiration date 0905)
For help to troubleshoot payment gateways, see General Troubleshooting and the documentation for your specific gateway.