Revision as of 18:30, 29 September 2021

Supported Features

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

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.

WebHook Endpoints

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 (for example, Apple® Pay). For customers who don’t use Apple Pay, Payment Request supports credit cards stored in the browser, Google® Pay, and Microsoft® Pay.

Apple Pay

The Apple Pay Button on Checkout

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

Microsoft Pay

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

ACH/SEPA

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

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

The Stripe payment workflow 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.

In WHMCS 7.8 and later, WHMCS uses the Stripe Elements implementation method. When performing checkout, if customer authorisation 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.

Recurring Payments

Automated recurring payments use stored tokens. If a client 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, 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 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. Go to Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways.
2. Activate the Stripe module.
3. Click Deactivate for your previous merchant gateway provider.
4. Select Stripe as the replacement gateway to switch users of the previous gateway module to.
5. Click OK.

Migrating from a 3rd 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, navigate to a client that you know has an active Stripe token and click Credit Card Information on the Client Summary page. Verify that the listed token includes the cus_ prefix.

To switch to the WHMCS Stripe module:

1. Activate the module as described above.
2. Deactivate your previous Stripe module.
3. Select the WHMCS Stripe module.
4. Remove any third-party files and template customisations.

Troubleshooting

Remote Transaction Failure. Please Contact Support

This issue has multiple causes (below). This may also display as 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 your 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 was blocked (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 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, these issues may trigger this error:

• A hook file in /includes/hooks/stripe.php. Remove this file when switching to the WHMCS Stripe module.
• Template customisations in your active order form template files.
• The payment method is set to a module other than Stripe. In this case, 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 or, prior to WHMCS 8.0, Setup > Payments > 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. 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

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 at Billing > Gateway Log for a failed payment attempt by an admin or the cron job, this indicates that the customer is in an European country or has a European billing address. Stripe's API requires that they make at least one manual payment to get added to their system.

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 and (click show child parameters).

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 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 administrators). Then, add the payment method again.

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

1. Go to Configuration () > System Settings > General Settings and select the General tab.
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.

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.

This can also be caused by 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, the custom JavaScript will need to be corrected.
• If the JavaScript error is coming from a third-party customisation, 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 in the Gateway Log at Billing > Gateway Log.

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 upon 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 or, prior to WHMCS 8.0, Setup > Payments > 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.