Stripe

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

For other Stripe options, see Stripe ACH and Stripe SEPA.

Supported Features

Type: Token

One-TimeRecurringRefundsReversals
✓✓✓✖️
3D SecureRemote Update CardRemote Delete CardAddPayMethod API
✓✓✓✖️
This payment gateway module is not compatible with the Modern or Boxes order form templates.

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. Generate publishable and restricted API keys using the WHMCS app in the Stripe App Marketplace.
  6. Copy and paste the API keys into WHMCS.
    If you used Stripe prior to October 2024, you must update Secret Stripe API Key to use a restricted API key instead of the previous secret key. For more information, see Restricted API Key Requirement below.
  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).

An SSL certificate is required to use Apple Pay.

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.

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

If you used this module prior to October 2024, you must replace the old secret key in your Stripe configuration with a restricted API key.

In January 2024, Stripe announced that it will require new secure authentication methods beginning on October 29, 2024.

If you use any Stripe payment gateway modules (Stripe, Stripe ACH, or Stripe SEPA), you must ensure that you have configured it to use a restricted API key for Secret Stripe API Key.

You can retrieve 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.

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.
WHMCS 8.3 and higher includes support for disputes for Stripe credit card transactions and some PayPal® transactions at Billing > Disputes.

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.

  • For more information, see Viewing Balances and Transactions.
  • In the Admin Area Dashboard, you can view your Stripe balances through the Stripe Balance widget.
    • This widget does not use the WHMCS\Module\Gateway\Balance and WHMCS\Module\Gateway\BalanceCollection classes to display balances.
    • For currencies to display in this widget, they must be active in your Stripe account and in WHMCS at Configuration () > System Settings > Currencies.

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

For more information about the additional Stripe requirements for Indian Stripe accounts, see Stripe’s documentation.

Troubleshooting

Remote Transaction Failure. Please Contact Support

This issue has multiple causes. This may also display as Error.

To resolve this issue:

  1. Go to Billing > Gateway Log.
  2. Check the Result and Debug Data columns for error messages or codes from the time of the payment attempt.
  3. Perform the appropriate steps in Stripe’s Error Codes and Declines Codes documentation.

See below for other common causes of this error:

Payment Blocked By Stripe

This indicates that a rule in your Stripe account may be blocking payment.

To resolve this:

  1. Log in to the Stripe Dashboard.
  2. Go to Developers > Logs.
  3. Find the log entries from the time at which the payment was attempted. The details of the log will show whether the payment failed (for example, with a The zip code you supplied failed validation error).
  4. Adjust the rules in your Stripe account for the error. For help, contact Stripe support.

Customisations

This issue may also present itself as No Stripe Details Found for Update in the Billing > Gateway Log.

This issue can occur due to interference from a third-party Stripe module. Using the official Stripe module requires the full uninstallation and removal of any custom or third-party Stripe integrations. This includes removal of all files and template modifications.

For example, the following issues may trigger this error:

  • A /includes/hooks/stripe.php hook file. Remove this file when switching to the WHMCS Stripe module.
  • Template customizations in your active order form template files.
  • The payment method uses a module other than Stripe. Perform one of the following actions:
    • Change the client’s Payment Method setting in the client’s Profile tab to the Stripe module.
    • Make Stripe the system default payment gateway at Configuration () > System Settings > Payment Gateways and choose All Payment Gateways.
Out-of-Date Template Files

The error indicates that you have out-of-date template files. Make certain that your client theme and order form templates are fully compatible with your version of WHMCS. The release notes for each version of WHMCS provide links to template changes.

Network Analyser Tool

Another method to diagnose this error is to use your browser’s network analyzer tool.

For more information, see Stripe Try Again Errors.

No Stripe Customer Details Found

The system logs this error in the debug data section of Billing > Gateway Log. It indicates that the client does not have a payment method in WHMCS. You can confirm this in the Pay Methods section of the client’s Summary tab.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click Pay Now to make a payment via Stripe. This will create a payment method to use for future automatic payments.

“You must provide a value for ‘cvc’

If you see this message at Billing > Gateway Log for a failed payment attempt by an admin or the cron job, this indicates that the customer is in a European country or has a European billing address. Stripe’s API requires that they make at least one manual payment.

To resolve this, ask the client to log in to the Client Area, go to the unpaid invoice, and click Pay Now to make a payment via Stripe.

For more information, see Stripe’s documentation.

When you do this, the system displays the following data:

cvc
usually required
Card security code. Highly recommended to always include this value, but it's only required for accounts based in European countries.

After the customer makes a manual payment, the system adds them to Stripe and any future attempts (automatic or manual) will work normally.

Network error [errno 35]: Unsupported SSL protocol version

This error indicates a server configuration issue. The server is attempting a secure connection to Stripe using an outdated SSL protocol. Most providers now require connections via TLS for security purposes.

For more information, see Stripe’s TLS documentation.

To resolve this issue, work with your system administrator or hosting provider to ensure that remote cURL connections use TLS by default. You may also need to update your OpenSSL version.

You passed an empty string for ‘statement_descriptor’

This indicates an empty Statement Descriptor field in the payment gateway configuration. Make certain that you set your entire gateway configuration.

Bad Request

This error may appear in the Client Area when a client attempts to pay for an invoice or order using an existing stored payment method. It indicates that the customer or the token in WHMCS do not exist in Stripe.

To ensure that the pay method is correctly stored in Stripe, delete the stored payment method from the Admin Area via the client’s profile’s Summary tab (which may display a more informative error to admins). Then, add the payment method again.

Customized or outdated system themes or order form templates can also cause this error. To troubleshoot this:

  1. Go to the General tab at Configuration () > System Settings > General Settings.
  2. Select Six or Twenty-One for System Theme.
  3. Go to the Ordering tab.
  4. Select a Default Order Form Template.
  5. Click Save Changes.
  6. Return to the Client Area and refresh the page.

We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future WHMCS version.

An unexpected error - No Stripe Payment Method found from token

This error indicates that the system could not transmit some of the required data to Stripe. This is usually due to outdated order form templates. Check this issue using the Twenty-One or Six system theme and the Standard Cart order form template.

We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future WHMCS version.

This can also be due to a JavaScript error from custom code (for example, template changes, hooks, or addons) preventing the standard Stripe JavaScript from running correctly. Your browser console will show whether a JavaScript error is occurring.

  • If one is, you must correct the custom JavaScript code.
  • If the JavaScript error is in a third-party customization, contact the developer for assistance.

If the issue persists, contact our support team.

Error Updating Remote Pay Method: Remote Storage Failed

You can find information about this error at Billing > Gateway Log.

payment-gateways token-gateway stripe

Last modified: October 31, 2024