Revision as of 12:10, 5 April 2022

About this Module

The WHMCS Stripe payment gateway uses Stripe's tokenised 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

Adding the Stripe Payment Gateway

Stripe Module Settings

To set up the Stripe payment gateway in WHMCS:

1. Go to Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Products/Services > Payment Gateways.
2. Choose the All Payment Gateways tab.
3. Click Stripe.
4. Check Show on Order Form to display this payment method in the Client Area during checkout.
5. Configure a display name. We recommend Credit Card.
6. Go to the Stripe portal and retrieve the publishable and secret API keys.
7. Enter your Stripe credentials.
8. Optionally, customize the Statement Descriptor Suffix with a maximum of 22 characters.
9. In WHMCS 8.0 and later, leave the Stripe WebHook Endpoint Secret and Stripe WebHook Endpoint Secret (Test/Sandbox) empty. WHMCS auto-generates these. See below for more information.
10. Optionally, check Allow Payment Request Buttons. See below for more information.
11. Click Save Changes.
12. 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 at Configuration () > System Settings > Currencies or, prior to WHMCS 8.0, Setup > Payments > 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. 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.

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.

Test Mode

This module does not support test mode.

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 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 our 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';

• Remove any third-party files and template customisations for the previous Stripe module.

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.