Revision as of 20:51, 12 December 2017

Supported Features

The WHMCS Official Stripe module was introduced in WHMCS 7.1.

Stripe is a tokenised gateway. As a result, customers personal 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

1. Begin by activating the Stripe module in Setup > Payments > Payment Gateways
2. Stripe uses API keys for authentication. Upon activation, you will be asked to enter the Secret and Publishable API Keys.
   • These can be found inside the Stripe portal at https://dashboard.stripe.com/account/apikeys
3. Customise the Display Name as desired, we recommend Credit Card
4. Enable Apple Pay if required
5. Customise the Statement Descriptor if required
6. Click Save Changes to complete the setup

Stripe is now active and ready for use.

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

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.
8. The stripe.js library is used for payments and card updates.

Migrating to Stripe

Our Stripe module supports migrating credit card details stored locally within WHMCS to the Stripe tokenisation system. This allows for a seamless transition from another merchant gateway provider to Stripe.

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

To migrate all of your credit card processing to Stripe, follow the steps below:

1. Navigate to 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. Then deactivate your previous Stripe module, and when prompted, select the new Stripe module to update and switch existing customers to.

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 on the Setup > Payments > Payment Gateways > Manage Existing Gateways tab 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

"You must provide a value for 'cvc'

If you see this logged under Billing > Gateway Log for a failed automatic 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.

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.