The WHMCS Stripe™ payment gateway uses Stripe’s tokenized storage system to submit credit card information to Stripe, which stores it remotely.

Supported Features #

Type: Token

Adding the Stripe Payment Gateway #

To set up the Stripe payment gateway in WHMCS:

1. Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
2. Click Stripe.
3. Check Show on Order Form to display this payment method in the Client Area during checkout.
4. Configure a display name. We recommend Credit Card.
5. Retrieve and configure your Stripe API credentials.
   • For WHMCS 8.11 and later, generate publishable and restricted API keys using the WHMCS app in the Stripe App Marketplace.
     We introduced support for Stripe Restricted API Keys in WHMCS 8.11. You cannot use Restricted API Keys with Stripe in WHMCS 8.10 or earlier.
     For steps and more information, see Add Restricted API Keys to Stripe.
   • For WHMCS 8.10 and earlier, go to the Stripe portal and retrieve the publishable and secret API keys.
6. Copy and paste the API keys into WHMCS.
7. Optionally, customize the Statement Descriptor Suffix with a maximum of 22 characters.
8. Leave Stripe WebHook Endpoint Secret and Stripe WebHook Endpoint Secret (Test/Sandbox) empty. WHMCS auto-generates these. See below for more information.
9. Optionally, check Allow Payment Request Buttons. See below for more information.
10. Click Save Changes.
11. If you use different default currencies in Stripe and WHMCS, make certain that you have also configured your Stripe account’s currency with a valid exchange rate in Configuration () > System Settings > Currencies. Stripe only returns transaction fees in the default currency for the Stripe account.

WebHook Endpoints #

Stripe’s WebHook Endpoints update WHMCS automatically with changes to your customers’ cards. When you click Save Changes, WHMCS will use Stripe Publishable API Key and Stripe Secret API Key to generate the Stripe WebHook Endpoint Secret and Stripe WebHook Endpoint Secret (Test/Sandbox).

• If you enter live API keys (rk_live), WHMCS will generate the Stripe WebHook Endpoint Secret.
• If you enter test API keys (rk_test), WHMCS will generate the Stripe WebHook Endpoint Secret (Test/Sandbox).

WHMCS registers the following WebHook Endpoints to deliver these events from Stripe:

• customer.source.updated
• customer.card.updated
• payment_method.updated

To change the WebHook ID, delete the current value in Stripe WebHook Endpoint Secret and Stripe WebHook Endpoint Secret (Test/Sandbox). Then, click Save Changes. WHMCS will auto-generate them again with new values.

Payment Request Button #

Enabling this option within the module configuration provides customers with a platform-specific payment request button (for example, Apple® Pay).

For customers who don’t use Apple Pay, Payment Request supports credit cards that the customer stored in the browser, Google® Pay, and Microsoft® Pay.

Apple Pay #

When you enable this, Apple Pay allows access to payment details that users have stored in their Apple Wallet. If they’re using Safari® on their iPhone® or iPad®, when they tap Buy with Apple Pay on your site, a payment window will appear. If they’re using Safari on their Mac® and have an iOS® device in range, their device will prompt them to authorize the payment.

To use Apple Pay with a live Stripe API key, you must register all of the domains that will display an Apple Pay button with Apple. This includes both top-level domains (for example, whmcs.com) and subdomains (for example, shop.whmcs.com).

To do this:

1. Download the domain association file and host it at /.well-known/apple-developer-merchantid-domain-association on your site. For example, if you’re registering https://example.com, host it at https://example.com/.well-known/apple-developer-merchantid-domain-association.
2. To instruct Stripe to register the domain with Apple, go to the Apple Pay tab in Account Settings in the Stripe Dashboard.

Google Pay #

Google Pay allows customers to make payments using any credit or debit card on their Google account, including Google Play, YouTube™, Chrome™, or an Android™ device.

Link #

In WHMCS 8.8 and later, customers can pay using Link for any Stripe transaction. Link makes payments easier by letting customers complete secure, one-click transactions using saved payment information. Stripe enables Link automatically.

For more information about disabling Link for your Stripe account, see How to Turn Off Link.

Microsoft Pay #

Microsoft Pay allows customers to make payments using any credit or debit card on their Microsoft account.

Test Mode #

This payment gateway module does not include a manual Test Mode setting. Instead, Stripe will detect whether you are using a live account or a test account using the API keys that you enter.

Restricted API Key Requirement #

In 2024, Stripe announced that it will require new secure authentication methods.

• If you use any Stripe payment gateway modules (Stripe, Stripe ACH, or Stripe SEPA), we strongly recommend updating your Stripe credentials to use restricted API keys as soon as possible.
• You can retrieve publishable and restricted API keys using the WHMCS app in the Stripe App Marketplace.

Payment Workflow #

This module supports automated recurring and on-demand billing.

Customers can choose between previously-stored cards or entering new ones during payment, and they can update their credit cards at any time in the Client Area. Admins can also update credit card information in the WHMCS Admin Area.

During checkout, clients never leave WHMCS. Personal card information goes directly to Stripe and is never stored within WHMCS. The Stripe API handles all refunds and obtains transaction information.

• WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorization is required, the system will prompt the user automatically to approve the payment. This process is also commonly referred to as 3D Secure. Use of 3D Secure depends on the card type and issuer.
• In WHMCS 8.8 and later, Stripe module transactions meet all Reserve Bank of India requirements.

Recurring Payments #

Automated recurring payments use stored tokens. If a client’s credit card requires SCA, the system will deny the payment attempt and the client must log in to WHMCS manually to process the payment.

Payment Gateway Balances #

In WHMCS 8.2 and later, you can view payment gateway balances directly within the WHMCS Admin Area, with native support for Stripe balances.

At Billing > Transactions List, you can view balances in the transaction list and in the transaction details for individual transactions.

This requires you to enable View Gateway Balances for the desired administrator role at Configuration () > System Settings > Administrator Roles.

Migrating to Stripe #

The Stripe payment gateway module supports migrating locally-stored credit card details to Stripe’s tokenized storage. This is useful when you transition from another non-tokenized merchant gateway provider to Stripe.

For an existing client with a locally-stored credit card, the first time that the system attempts to capture payment for an invoice using Stripe, the system will submit the credit card details to Stripe and create and store a token. Then, the system will remove the local copy of the card details.

To migrate to Stripe and ensure all future credit card processing uses it:

1. Contact Stripe Support to submit the required PCI compliance documentation to request access to raw card data APIs.
   To process Stripe transactions, must certify PCI compliance with Stripe and have access to Stripe’s raw card data APIs. For more information, see Stripe PCI Compliance Issues or Stripe’s documentation.
2. Go to the appropriate location for your version of WHMCS:
   • For WHMCS 8.6 and later, go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
   • For WHMCS 8.5 and earlier, go to Configuration () > System Settings > Payment Gateways and choose All Payment Gateways.
3. Activate the Stripe module.
4. Click Deactivate for your previous merchant gateway provider.
5. Select Stripe as the replacement gateway to switch users of the previous gateway module to.
6. Click OK.

Migrating from a Third-Party Stripe Module #

The WHMCS Stripe module uses the Stripe cus_ reference to capture payments (for example, cus_9MvIb7UlgJfJTn). The WHMCS Stripe module can replace any third-party module that uses this.

To check whether your current Stripe module uses the cus_ reference, go to a client that you know has an active Stripe token and click on one of the pay methods in the Summary tab of the client’s profile. Verify that the listed token includes the cus_ prefix.

To start using the WHMCS Stripe module:

1. Note the internal name of the previous Stripe module, which you can find by looking in the gateway column in the tblpaymentgateways database table.

2. Activate WHMCS’s official Stripe module.

3. Deactivate the previous Stripe module.

4. Check one of the Stripe pay methods on a client. If the token contains cus{_}, you can use it with our module but it will require a manual database edit first. To allow that, run the following SQL query using phpMyAdmin or another tool, replacing example with the name of the previous module:

   UPDATE tblpaymethods SET gateway_name = 'stripe' WHERE gateway_name = 'example';
   

5. Remove any third-party files and template customizations for the previous Stripe module.

Stripe India Accounts #

India-based Stripe accounts require the following additional conditions for a successful payment capture:

• The client’s address and billing contact must use a valid Indian postal address.
• The payment card must be from an Indian bank.
• The invoice must use INR as the currency.

To automatically convert invoice totals into other currencies on payment in WHMCS:

1. Go to Configuration () > System Settings > Currencies.
2. Add INR as an additional currency.
3. Go to Configuration () > System Settings > Payment Gateways.
4. Set Convert To For Processing on the Stripe gateway to INR.

Troubleshooting #

You can find information about most payment gateway-related errors in the logs at Billing > Gateway Log and in the Module Log.

You may encounter the following common issues:

Last modified: 2025 March 25