Payment Gateways

Payment gateway modules allow you to accept payments of many types directly within WHMCS.

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.

You can access this feature at Configuration () > System Settings > Payment Gateways.

Activating a Payment Gateway

To activate a new payment gateway, find it in the list of payment gateways and click Activate. Then, configure the necessary gateway settings.

For steps to activate and configure a payment gateway, see Configure a Payment Gateway.

Payment Gateway Configuration

Each gateway has its own specific API requirements in order to process transactions, which vary from gateway to gateway.

For more information on your payment gateway’s configuration, see the documentation for that module.

All gateways can use the following settings:

Show on Order FormWhether 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.
Display NameThe gateway’s name throughout the system and to clients (for example, an gateway could use the visible name Credit Card).
Convert To For ProcessingIf you use a payment gateway that doesn’t accept all of your currencies, you can choose a currency for WHMCS to convert to using the rates at Configuration () > System Settings > Currencies.
For more information, see Convert Invoices to a New Currency.

Supported Gateway Modules

WHMCS includes support for Merchant, Third-Party, Tokenization, and Manual gateways.

Merchant Gateways

Merchant Gateways store credit card information securely in the WHMCS database.

Third-Party Gateways

Third-Party Gateways direct the client to the provider’s website to process payments off-site.

Tokenization Gateways

Tokenization Gateways reduce PCI liabilities for repeat billing by storing the original transaction details or a reference number (token) and not the full credit card number.

For more information, see Tokenization.

Manual Gateways

Manual Gateways provide support for manual transactions in WHMCS.

Email Templates

The type of payment gateway that you select influences which invoice notification email template it sends.

  • Third-party gateways send the Invoice Created email template.
  • Merchant and tokenization gateways send the Credit Card Invoice Created email template.

This allows you to customize the payment instructions to clients for the different payment processes.

Attempt Capture

The type of payment gateway that you select influences the behavior when you click Attempt Capture on the invoice page in the Admin Area.

  • For third-party gateways, the system will deactivate Attempt Capture because the client must click the payment button on the invoice to send payment.
  • For merchant gateways and tokenization gateways, Attempt Capture will be active and staff can click to instantly capture payment from the client’s credit card.

Deactivating Gateway Modules

For instructions to stop using one payment gateway and switch to another, see Migrate Payment Gateways.

When you stop using a payment gateway, you must deactivate it. Deactivation prevents new payments using this gateway and will automatically reassign any 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. Make sure to change any currently-assigned items to this gateway.

Viewing Balances and Transactions

We added this feature in WHMCS 8.2.

You can view payment gateway balances for Stripe™, PayPal Basic, PayPal Payments, and PayPal Card Payments at Billing > Transactions List in the WHMCS Admin Area. This lets you check your financial details sooner and stay aware of trends and changes.

  • The displayed balances remain in the cache for a specific amount of time and will then automatically refresh. You can also manually refresh them.
  • When you click on a transaction in this list, additional information will display for that transaction.
  • Balances display by default for admins with the Full Administrator role. To make this information available to other admins, assign the View Gateway Balances permission to the desired role.
If you use Stripe, you can also view balances in an Admin Area Dashboard widget.
For information about displaying balances in custom development, see our Developer Documentation.

Test Credit Card Numbers

Gateways often have test modes that can use test card numbers. The common test card numbers below can generate successful test transactions, but they can vary from gateway to gateway.

You may use any expiration date in the future:

Card NumberDescription
4007000000027Visa® Test Card
4012888818888Visa Test Card II
4000000000000002Visa Test Card III
5424000000000015MasterCard® Test Card
370000000000002American Express Test Card
6011000000000012Discover Test Card
3088000000000017JCB Test Card (Use expiration date 0905.)
38000000000006Diners Club/Carte Blanche Test (Use expiration date 0905.)

Last modified: June 24, 2024