The Stripe Dynamic Payments module uses the Stripe™ Optimized Checkout Suite (OCS) to process payments. It displays eligible payment methods based on transaction and customer context, such as currency, amount, and location.

Supported Features #

Type: Token

Adding the Stripe Dynamic Payments Gateway #

To set up the Stripe Dynamic Payments gateway in WHMCS:

1. Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
2. Click Stripe Dynamic Payments.
3. Check Show on Order Form to display this payment method in the Client Area during checkout.
4. Configure a display name.
5. Generate publishable and restricted API keys using the WHMCS app in the Stripe App Marketplace.
   For steps and more information, see Add Restricted API Keys to Stripe.
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. Click Save Changes.
10. 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’ payment methods. 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:

• payment_method.updated
• charge.failed
• charge.succeeded

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.

Link #

Stripe Dynamic Payments supports Link to help returning customers complete checkout faster.

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.

Supported Currencies #

Stripe Dynamic Payments only supports currencies that Stripe supports. If an invoice or order uses an unsupported currency, Stripe Dynamic Payments will not display as a payment option.

Payment Workflow #

This module supports automated recurring and on-demand billing.

Customers can use previously-stored payment methods or enter new ones during payment, and they can update payment methods at any time in the Client Area.

During checkout and invoice payment, clients never leave WHMCS. Sensitive payment information goes directly to Stripe and WHMCS never stores it.

• 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.
• 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 Strong Customer Authentication (SCA), the system will deny the payment attempt and the client must log in to WHMCS manually to process the payment.

Payment Gateway Balances #

You can view payment gateway balances directly within the WHMCS Admin Area, with native support for Stripe Dynamic Payments 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 Dynamic Payments #

The Stripe Dynamic Payments 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.

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 Dynamic Payments, 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 Dynamic Payments 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, you 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 Configuration () > Apps & Integrations or Addons > Apps & Integrations.
3. Activate the Stripe Dynamic Payments module.
4. Click Deactivate for your previous merchant gateway provider.
5. Select Stripe Dynamic Payments 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 Dynamic Payments module uses the Stripe cus_ reference to capture payments (for example, cus_9MvIb7UlgJfJTn).

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 one of the payment methods in the Summary tab of the client’s profile. Verify that the listed token includes the cus_ prefix.

To start using Stripe Dynamic Payments:

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 the Stripe Dynamic Payments module.

3. Deactivate the previous Stripe module.

4. Check one of the Stripe payment methods on a client. If the token contains cus_, you can use it with this module but it may 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 and stripe_dynamic_payments with the Stripe Dynamic Payments gateway name in your installation:

   UPDATE tblpaymethods SET gateway_name = 'stripe_dynamic_payments' 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 Dynamic Payments 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: 2026 March 31