Revision as of 11:56, 20 October 2020

Supported Features

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

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

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

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.

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.

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

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

May also present itself as "No Stripe Details Found for Update" in the Gateway Log.

This issues usually occurs due to interference from a 3rd 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.

The above errors may also be caused by out of date template files. Please refer to the Standard Cart changes in 7.1 as itemised at the following URL and ensure any custom checkout.tpl template files are updated with these changes: https://github.com/WHMCS/orderforms-standard_cart/commit/3f937105958aabadbc93cbdcfa6af7e05b1edc6d

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 show client side when attempting to pay for an invoice/order using an existing stored pay method. It indicates the customer and/or token stored within WHMCS do not exist within Stripe. Deleting the stored pay method (card) from within the admin user interface via the client's Summary tab (which may display a more informative error to administrators) and adding the pay method (card) again should ensure it's correctly stored with Stripe and resolve this.

It can also be caused by customised or outdated theme or order form templates. Please switch temporarily to the stock templates to help eliminate those as a problem:

• Select the Six system template via Configuration () > System Settings > General Settings > General Tab
• Select and one of the Standard Order Form Templates via Configuration () > System Settings > General Settings > Orders Tab
• Click Save Changes
• Return to the client area and refresh the page to try again

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 and most commonly occurs due to outdated templates. Test using the Six client area template and Standard Cart order form template, then 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