WHMCS Stripe integration means activating one of the Stripe payment gateway modules that ship with WHMCS, at Configuration > Apps & Integrations, and pasting in a publishable key and a restricted API key from the WHMCS app in the Stripe App Marketplace. WHMCS registers its own webhook with Stripe when you save. The official documentation has no step where you add a callback URL by hand.
Which Stripe module should you use in WHMCS?
Use Stripe Dynamic Payments if your WHMCS version has it, because the WHMCS 9.0 documentation names it as the recommended Stripe module. The documentation lists four Stripe modules, and none of them is called "Stripe Payments".
| Module | What it takes | 3D Secure | What the documentation says |
|---|---|---|---|
| Stripe Dynamic Payments | The payment methods Stripe finds eligible for the currency, amount and customer location | Yes | Recommended. Uses Stripe's Optimized Checkout Suite. |
| Stripe | Cards, plus optional payment request buttons | Yes | The older card module. Not compatible with the Modern or Boxes order form templates. |
| Stripe ACH | Bank account debits by ACH | No | Does not support Plaid. A payment can take up to five days, and the invoice stays at Payment Pending until it clears. |
| Stripe SEPA | SEPA Direct Debit, EUR invoices only | No | Confirmation can take up to 14 business days. The invoice stays at Payment Pending until then. |
All four are token gateways with one-time payments, recurring payments and refunds. None supports reversals. I found a Stripe Dynamic Payments page in the 9.0 documentation and none in the 8.13 documentation, so an older install may only offer the other three.
Which API keys does the WHMCS Stripe module need?
It needs two: a publishable key and a restricted API key. The restricted key starts with rk_ and goes into the field labeled Stripe Secret API Key. An old secret key starts with sk_, and the documentation says a module still configured with one must be updated.
WHMCS documents the steps in Add Restricted API Keys to Stripe:
- Open the WHMCS app listing in the Stripe App Marketplace and click Install app.
- For Install in, choose live mode or test mode, then install.
- Click Continue to app settings and copy the Restricted key value.
- In WHMCS, go to Configuration > System Settings > Payment Gateways, open the Stripe module, paste the key into Stripe Secret API Key and click Save Changes.
Repeat this for each Stripe module you run. Stripe ACH and Stripe SEPA also have a Use Stripe Configuration checkbox that reuses the keys from the Stripe module.
How do you set up the Stripe gateway in WHMCS?
You activate it at Configuration > Apps & Integrations, or Addons > Apps & Integrations, and fill in a short form.
- Click the module, for example Stripe Dynamic Payments.
- Check Show on Order Form and set a display name. The Stripe page suggests "Credit Card".
- Paste the publishable key and the restricted key.
- Optionally fill in Statement Descriptor Suffix.
- Leave Stripe WebHook Endpoint Secret and Stripe WebHook Endpoint Secret (Test/Sandbox) empty.
- Click Save Changes.
If Stripe and WHMCS have different default currencies, add the Stripe account's currency with a valid exchange rate at Configuration > System Settings > Currencies; the WHMCS multi currency setup guide walks through that screen. My guide on how to set up WHMCS covers the rest of a new install.
How does WHMCS handle Stripe webhooks?
WHMCS registers the webhook with Stripe itself when you click Save Changes, using the keys you entered. Live keys fill the Stripe WebHook Endpoint Secret field. Test keys fill the Test/Sandbox field.
- Stripe registers for
customer.source.updated,customer.card.updatedandpayment_method.updated, so a card change at Stripe reaches WHMCS. - Stripe Dynamic Payments registers for
payment_method.updated,charge.failedandcharge.succeeded. - Stripe ACH and Stripe SEPA call the field Webhook Secret Key. It is generated for you as well. Both modules need a valid webhook and secret to recognize a payment and apply it to the invoice. If you change the secret at Stripe, update it in WHMCS.
To make WHMCS generate new values, delete what is in both secret fields and save again.
An earlier version of this guide had you add an endpoint in the Stripe Dashboard with a callback file path and an event list. None of that is in the official documentation, so I removed it.
Does WHMCS Stripe support Apple Pay and Stripe Checkout?
Apple Pay is supported by the Stripe module through a setting called Allow Payment Request Buttons. For all four modules, the documentation says the customer never leaves WHMCS during checkout, and it describes no redirect to a checkout page hosted by Stripe.
With the setting on, the customer sees a button for their platform: Apple Pay, Google Pay, Microsoft Pay or a card saved in the browser. Apple Pay with a live key needs three things:
- An SSL certificate on the site.
- Stripe's domain association file at
/.well-known/apple-developer-merchantid-domain-associationon every domain and subdomain that shows the button. - Each domain registered on the Apple Pay tab of the account settings in the Stripe Dashboard.
The card form is Stripe Elements, embedded in the WHMCS page, and card details go straight to Stripe. The Stripe Dynamic Payments page lists no individual wallets. It says the module shows whichever methods are eligible for the transaction.
How do stored cards, renewals and 3D Secure work?
WHMCS stores a Stripe token, not the card, and charges that token when an invoice is due.
- Stored payment methods. Customers can pay with a stored card or enter a new one, and can change cards in the Client Area. With the Stripe module an admin can also update a card. With Stripe Dynamic Payments, a payment method can only be added from the Client Area.
- 3D Secure. There is no switch for it. If the bank requires authorization at checkout, WHMCS prompts the customer automatically. Whether that happens depends on the card type and the issuer.
- Renewals. If a stored card requires Strong Customer Authentication during an automated capture, WHMCS denies the attempt, and the client has to log in and pay manually.
- Retries. How often a declined card is tried again is set under Payment Capture Settings at Configuration > System Settings > Automation Settings.
What should the Stripe statement descriptor be in WHMCS?
Keep it short. WHMCS has an optional Statement Descriptor Suffix field that accepts up to 22 characters, but Stripe's limit of 22 covers the whole descriptor.
Stripe's statement descriptor rules say a complete descriptor has 5 to 22 Latin characters, at least one letter, and none of < > \ ' " *. For card payments, Stripe joins the prefix from your Stripe account (2 to 10 characters), an asterisk, a space and the suffix. A 7-character prefix therefore leaves 13 characters for the suffix.
If the Gateway Log shows You passed an empty string for 'statement_descriptor', a descriptor setting is empty in the module configuration.
How do you test WHMCS Stripe with test keys?
You test by entering test keys, because none of the modules has a Test Mode switch. Stripe decides from the key whether a request is live or test.
Install the WHMCS app at Stripe in test mode to get an rk_test key. Enter it on a staging copy of WHMCS, with Disable Email Sending turned on in the Mail tab of General Settings so test invoices do not reach real clients. Then pay test invoices with cards from Stripe's testing page, using any future expiry date and any three-digit CVC.
| Test card | What Stripe simulates |
|---|---|
4242 4242 4242 4242 | A Visa payment that succeeds |
4000 0025 0000 3155 | Authentication required, unless the card was set up for future payments |
4000 0027 6000 3184 | Authentication required on every transaction. Try an automated renewal with it. |
4000 0000 0000 9995 | A decline for insufficient funds |
4000 0000 0000 0002 | A generic decline |
Read Billing > Gateway Log after each attempt. Do not run a "small real charge" on live keys as a test: Stripe's testing page says its services agreement prohibits testing in live mode with real payment details.
What goes wrong with WHMCS Stripe, and when is it the wrong fit?
Most failures are written to Billing > Gateway Log, and the documentation maps the common messages to causes.
| Message or symptom | Documented cause |
|---|---|
No Stripe Customer Details Found | The client has no payment method in WHMCS. |
No Stripe Payment Method found from token | Data did not reach Stripe, often because of a customized or outdated theme or order form template, or a JavaScript error in custom code. |
Remote Transaction Failure. Please Contact Support | Several causes. Read the Result and Debug Data columns, then the logs at Stripe. Leftovers from a third-party Stripe module, such as a hook file at /includes/hooks/stripe.php, are one of them. |
Unsupported SSL protocol version | The server connects to Stripe with an outdated SSL protocol. |
| Stripe Dynamic Payments is missing at checkout | Stripe does not support the transaction currency. |
Know the limits before you commit:
- Bank debits do not suit instant activation. ACH and SEPA invoices stay at Payment Pending for days.
- Moving cards stored locally under another gateway into Stripe needs PCI compliance documentation and access to Stripe's raw card data APIs, which you request from Stripe.
- The documentation describes recurring billing as WHMCS charging stored tokens. It does not describe subscriptions managed on the Stripe side, so do not plan around them.
If you want this configured or debugged on a staging copy, see my WHMCS payment gateway integration service or hourly WHMCS developer work; a free scoping call of about 30 minutes comes first, and a written quote follows within one business day.
Last reviewed 10 October 2026. Disclosure: I am a freelance WHMCS developer and I sell payment gateway setup and troubleshooting, so I am not neutral. I am CTO at ElySpace, a freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI. Module names, settings and limits come from the WHMCS 9.0 and Stripe documentation as I read them on that date.
