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.

Sensitive payment information goes directly to Stripe and WHMCS never stores it. Clients remain in WHMCS during checkout and invoice payment unless they use a redirect payment method.

• 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.

Redirect Payment Methods #

A redirect payment method sends the client to the provider’s website to approve the payment and then returns them to WHMCS. Stripe Dynamic Payments supports the redirect payment methods that you enable in your Stripe Dashboard, including PayPal®, Amazon Pay, iDEAL, Bancontact, and BLIK.

Availability depends on whether the client has logged in:

• Authenticated clients can choose a redirect payment method during checkout and when they pay an invoice. They can also choose a previously-stored redirect payment method.
• Visitors who have not logged in do not see redirect payment methods during checkout. To use one, they must log in to WHMCS or create an account first.

When a client returns from the provider, WHMCS returns them to the checkout and preselects the payment method that they chose.

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 from Legacy Stripe Modules #

You can migrate stored payment methods from the Stripe, Stripe ACH, and Stripe SEPA modules to Stripe Dynamic Payments without requiring clients to re-enroll.

Admin Area Migration #

A Migrate from Legacy Stripe Payment Gateways button appears on the Stripe Dynamic Payments configuration page when both of the following statements are true:

• Stripe Dynamic Payments is active, and you have configured a secret key and webhook.
• At least one legacy Stripe module (Stripe, Stripe ACH, or Stripe SEPA) is active.

Clicking Migrate from Legacy Stripe Payment Gateways opens an interface that lists each active legacy gateway with at least one stored payment method:

• Each listed gateway shows the number of payment methods it will reassign.
• Each gateway is selected by default. Deselect one to exclude it from the migration.

Click Migrate to submit.

Before you migrate, the interface checks the following:

Credentials #

A payment token only works with the Stripe account that created it, so WHMCS compares each legacy gateway’s API credentials to those of Stripe Dynamic Payments, both in the interface and again on the server when you submit. WHMCS disables the gateway’s checkbox if:

• A legacy gateway is configured with a different Stripe account than Stripe Dynamic Payments.
• A legacy gateway has stored payment methods but no saved Stripe API credentials.

ACH and SEPA Exclusions #

For Stripe ACH and Stripe SEPA, WHMCS skips the following types of accounts:

• Accounts that are pending microdeposit verification.
• Accounts using the legacy Sources API (tokens that use the ba_ prefix).

You must re-enroll these through Stripe Dynamic Payments after migration.

Clients With a Pending Payment #

WHMCS skips a client if any of their invoices has the Payment Pending status. All of that client’s legacy Stripe tokens migrate automatically if nothing is pending the next time you run the migration.

WHMCS shows the result immediately in the interface for a migration it can complete right away. For a larger migration, WHMCS queues the work instead. It completes on the next automation (cron) run. The system cron must be running, or WHMCS never processes the queued remainder.

To finish a queued migration immediately instead of waiting for cron, run one of the following commands from the WHMCS root directory:

php crons/cron.php do --RunJobsQueue

php modules/gateways/stripe_dynamic/bin/migrate.php --confirm

After a migration completes, WHMCS:

1. Reassigns all selected stored payment methods to Stripe Dynamic Payments.
2. Updates the default payment gateway for affected clients. Clients that default to a different gateway, such as PayPal®, keep their existing default.
3. Updates payment gateway references on hosting accounts, domains, service addons, orders, invoices, invoice line items, and transaction records.

WHMCS writes migration progress, per-gateway totals, and errors to the Activity Log at Configuration () > System Logs.

CLI Migration Tool #

To migrate large volumes of payment methods, run the modules/gateways/stripe_dynamic/bin/migrate.php script from the WHMCS root directory. We recommend that you run it using the --dry-run flag before running the live migration. Verify the output before you deactivate the legacy gateways.

The tool exits with a 0 value if it succeeds and a 1 value if it encounters token-level errors or an unexpected exception.

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 September 30