Stripe

Supported Features

Type	One Time	Recurring	Refunds	3D Secure
Token	Yes	Yes	Yes	Yes

Remote Update Card	Remote Delete Card	AddPayMethod API
Yes	Yes	No

The WHMCS Stripe payment gateway uses Stripe's tokenised storage system. As a result, credit card information is submitted to and stored remotely by Stripe. Using a tokenised gateway is recommended for security and reduced liability.

Setup

Stripe Module Settings

To configure Stripe:

1. Go to Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways.
2. In All Payment Gateways, choose Stripe.
3. Customize the Display Name. We recommend setting this to Credit Card.
4. Go to the Stripe portal and retrieve the publishable and secret API keys. Stripe uses API keys for authentication.
5. In WHMCS, enter the Stripe Publishable API Key and Stripe Secret API Key.
6. Optionally, customize the Statement Descriptor Suffix with a maximum of 22 characters.
7. In WHMCS 8.0 and later, leave the Stripe WebHook Endpoint Secret and Stripe WebHook Endpoint Secret (Test/Sandbox) empty. WHMCS auto-generates these.
8. Optionally, check Allow Payment Request Buttons.
9. Click Save Changes.

Stripe is now active and ready for use.

Transaction Fees
Stripe returns transaction fees in the default currency of the Stripe account. If you have a different default currency in WHMCS, you must ensure you have configured the currency of your Stripe account in Configuration () > System Settings > Currencies or, prior to WHMCS 8.0, Setup > Payments > Currencies. This must include a valid exchange rate to allow WHMCS to be able to convert the fee into your other currencies.

Warning
The Stripe payment gateway module is not compatible with the Modern or Boxes order form templates.

WebHook Endpoints

Stripe Webhooks can be utilised in WHMCS v8.0 and above.

Stripe's WebHook Endpoints update WHMCS automatically with changes to your customers' cards. In WHMCS 8.0 and later, when you click Save Changes, WHMCS will use the 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 (sk_live), WHMCS will generate the Stripe WebHook Endpoint Secret.
• If you enter test API keys (sk_test), WHMCS will generate the Stripe WebHook Endpoint Secret (Test/Sandbox).

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

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

To change the WebHook ID, empty Stripe WebHook Endpoint Secret and Stripe WebHook Endpoint Secret (Test/Sandbox) and 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 such as Apple Pay. For customers who don’t use Apple Pay, the Payment Request button supports browser-saved cards, Google Pay, and Microsoft Pay.

Apple Pay

The Apple Pay Button on Checkout

When enabled, Apple Pay allows access to payment details that users have stored in their Wallet. If they're using Safari on their iPhone or iPad, when they tap "Buy with Apple Pay" on your site, they'll be shown a modal payment sheet. If they're using Safari on their Mac, and have an iOS device in range, they'll be prompted on their device to authorize the payment, which will then be sent to the browser.

Enabling Apple Pay

To use Apple Pay with a live Stripe API key, it is required to register with Apple all of your web domains that will be showing an Apple Pay button. This includes both top-level domains (e.g. whmcs.com) and subdomains (e.g. shop.whmcs.com).

An SSL Certificate is required to use Apple Pay

1. Download this 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, make that file available at https://example.com/.well-known/apple-developer-merchantid-domain-association.
2. Next, tell Stripe to register the domain with Apple. This is done by going to the Apple Pay tab in the Account Settings of Stripe Dashboard

Google Pay

Google Pay allows customers to make payments using any credit or debit card saved to their Google Account, including ones from Google Play, YouTube, Chrome, or an Android device.

Microsoft Pay

Microsoft Pay allows customers to make payments using any credit or debit card saved to their Microsoft Account.

ACH/SEPA

Support for ACH and SEPA was introduced in WHMCS 7.9.

Stripe ACH and Stripe SEPA are payment gateways that allow bank payments in the US and the Euro Zone respectively.

Per Stripe requirements, ACH is currently supported only for Stripe businesses based in the U.S. and only in USD.

Stripe users in Europe and the United States can accept SEPA Direct Debit payments from customers in countries within the Single Euro Payments Area (EUR only).

Payment Workflow

The Stripe module on Checkout

1. Automated recurring and on-demand billing is supported.
2. When making a payment, customers are able to select to use a previously stored card or enter a new one.
3. Customers can update their credit card at any time from the client area.
4. Admin level users with the necessary permissions can also perform card updates from the admin area.
5. Customers never leave your WHMCS installation during checkout or updating their card.
6. Personal card information is submitted directly to Stripe and is never stored in your local WHMCS installation.
7. The Stripe API is used for refunds and obtaining transaction information.

In WHMCS 7.8 and later, WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorisation is required, the user will be automatically prompted via modal 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.

WHMCS 8.3 and higher includes support for disputes for Stripe and PayPal® transactions at Billing > Disputes.

Recurring Payments

Automated recurring payments are performed using stored tokens. If a client card requires SCA, the payment attempt will be denied and the client will be required to login to WHMCS to manually 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, you can view balances in the transaction list and in the transaction details for individual transactions. For more information, see Payment Gateway Balances and Transactions.

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

Admin Area Dashboard Widget
In the Admin Area Dashboard, you can view your Stripe balances through the Stripe Balance widget. However, this widget does not use the WHMCS\Module\Gateway\Balance and WHMCS\Module\Gateway\BalanceCollection classes to display balances. For more information, see Stripe Balance Widget.

Migrating to Stripe

The Stripe payment gateway module supports migrating credit card details stored locally within WHMCS to Stripe's tokenized storage. This allows for a seamless transition from another non-tokenized merchant gateway provider to Stripe.

For an existing client with a credit card stored locally, the first time a payment capture is automatically attempted for an invoice using Stripe using a locally stored credit card, the credit card details will be submitted to Stripe and a token created and stored. The previously locally stored card details will be removed.

To migrate to Stripe and ensure all future credit card processing is done using it, follow the steps below:

1. Navigate to Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways.
2. Ensure the Stripe module has been activated
3. Select the Deactivate link for your previous merchant gateway provider
4. When prompted to choose a replacement gateway to switch users of the previous gateway module to, select Stripe
5. Click OK to complete the process

Note: Existing credit card details stored locally will be sent to Stripe and converted to a token the first time a payment is automatically attempted for a client using the Stripe module. Until that time, credit card details will remain stored locally within WHMCS.

Migrating from a 3rd Party Stripe Module

The Official WHMCS Stripe module uses the Stripe "cus_" reference to capture payments - e.g. cus_9MvIb7UlgJfJTn. For any 3rd party module which also uses this reference, the official module can replace it.

To verify if your current Stripe module uses the "cus_" reference, navigate to a client you know to have an active Stripe token and click the Credit Card Information link on the Client Summary page. Verify the token listed there has the "cus_" prefix.

To convert to the Official Stripe module:

• Activate the module as described above,
• Deactivate your previous Stripe module,
• When prompted select the official Stripe module to update and switch existing customers to,
• Remove all files and template customisations (if applicable) required by the 3rd party module.

Troubleshooting

The following are some common issues and their suggested solutions.

Remote Transaction Failure. Please Contact Support

There are a number of causes for this. This issue may also present itself as simply "Error" being displayed.

Payment Blocked By Stripe

The payment may be blocked by a rule within your Stripe account. Please log in to your Stripe Dashboard and proceed to Developers > Logs. Locate the log entries captured at the time the payment was attempted. The details of the log will show if the payment was blocked (for instance, with an error such as The zip code you supplied failed validation). Your Stripe rules can then be adjusted directly within your Stripe account as required. Please contact Stripe support for any assistance needed with adjusting your rules.

Customisations

It may also present itself as "No Stripe Details Found for Update" in the 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 any template modifications. Known modifications that can trigger this error include:

• A hook file present in /includes/hooks/stripe.php. This file should be removed when switching to the Official Stripe module.
• Template customisations present in your active order form template files.
• The payment method is set to a module other than Stripe. There are two solutions:
  • Change the client's Payment Method setting to the Stripe module. This is done under the client's Profile tab.
  • Make Stripe the system default payment gateway. This done by using the green arrows at Configuration () > System Settings > Payment Gateways > Manage Existing Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways > Manage Existing Gateways to move Stripe to the top of the page.

Out Of Date Template Files

The error may also be caused by out of date template files. Please ensure your client theme and order form templates are fully compatible with the version of WHMCS you are running. With each version of WHMCS the release notes provide links to template changes.

Network Analyser Tool

Another method to diagnose this error is to use your browser's network analyser tool. Please see the section Another Error Type in this help article. Whilst the article is for another issue, it describes how to use your browser's network analyser tool to help identify underlying errors.

No Stripe Customer Details Found

This error will be logged in the debug data section of the Billing > Gateway Log. It means that the client in quesiton does not have a Pay Method in WHMCS to make a payment charge via Stripe. You can confirm this by looking at the Pay Methods section of the client's Summary tab.

To resolve, invite the client to login to the client area, navigate to the unpaid invoice and click "Pay Now" to make a payment via Stripe. This will then create a Pay Method to be used for future automatic payments.

"You must provide a value for 'cvc'

If you see this logged under Billing > Gateway Log for a failed payment attempted by the admin or the cron job, this generally means the customer is in an European country or has an European billing address, and Stripe's API requires they make at least one manual payment to get added to their system. Having them pay an Unpaid invoice via the client area should resolve this. This functionality of their API is documented at https://stripe.com/docs/api?lang=python#create_card_token (click the "show child parameters" link to see it).

It shows the following when you do so:

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

Once the customer has made a manual payment as described above, they will be added to Stripe and any future attempts (either automatic or manual) should work as expected.

Network error [errno 35]: Unsupported SSL protocol version

Seeing this "Unexpected error communicating with Stripe" error in the Gateway Log indicates a server configuration issue. The server is attempting a secure connection to Stripe using an outdated SSL protocol. As this is no longer secure, most providers now require connections be made using the newer TLS protocol instead: Stripe TLS Documentation.

To resolve this issue, work with a server admin or hosting provider to ensure that remote cURL connections are made using the TLS protocol by default, rather than the outdated SSL protocol. Updating the OpenSSL version may also be required.

You passed an empty string for 'statement_descriptor'

This error is caused by an empty Statement Descriptor field in the payment gateway configuration. Please ensure a value is entered into the field in the gateway configuration - it cannot be left empty.

Bad Request

This error may appear in the Client Area when attempting 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 administrators). Then, add the payment method again.

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

• Go to Configuration () > System Settings > General Settings and select the General tab.
• Select Six or Twenty-One for System Theme.
• Go to the Ordering tab.
• Select a Default Order Form Template.
• Click Save Changes.
• Return to the client area and refresh the page.

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

An unexpected error - No Stripe Payment Method found from token

This error indicates that some of the required data is not being transmitted to Stripe. This is usually due to outdated order form templates. Please test using the Twenty-One or Six system themes and the Standard Cart order form template.

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

This can also be caused by a JavaScript error from custom code (template changes, hooks, addons, etc.) preventing the standard Stripe JavaScript from running correctly. Your browser console will show if a JavaScript error is occurring and, if so, the custom JavaScript will need to be corrected. If the JavaScript error is coming from a third party customisation, please contact the developer for assistance.

Please contact our support team if the issue persists.

Error Updating Remote Pay Method: Remote Storage Failed

A more informative reasoning for this error should be found in the Gateway Log at Billing > Gateway Log and will likely be self explanatory or covered by other errors featured in this troubleshooting section.

Stripe India Accounts

For Indian based Stripe accounts, the following additional conditions are required for a successful payment capture:

• Clients Address/Billing Contact must be a valid Indian postal address
• Payment card must be issued by an Indian bank
• Invoice must use INR currency

WHMCS can automatically and transparently convert invoice totals into other currencies upon payment:

• Navigate to Setup > Payments > Currencies

Add INR as an additional currency (if you haven't already)

• Navigate to Configuration () > System Settings > Payment Gateways > Manage Existing Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways > Manage Existing Gateways.
• Set the "Convert To For Processing" option on the Stripe gateway to INR.

More information on using the Convert to For Processing feature can be found here.

Further information on the additional Stripe requirements for Indian Stripe accounts can be found here: https://support.stripe.com/questions/requirements-for-india-export-charges