Stripe is the simplest way to accept credit and debit cards in WHMCS. The built-in Stripe module stores card tokens at Stripe (never on your server), supports 3D Secure, and lets WHMCS charge recurring invoices automatically. This guide covers the setup and the settings that prevent failed renewals.
Before you start
- A verified Stripe account with payouts enabled.
- WHMCS on HTTPS with the correct System URL.
- The WHMCS cron running, because automatic charges happen during the daily cron. See WHMCS cron and automation.
Get your API keys
- Log in to the Stripe Dashboard.
- Go to Developers → API keys.
- Copy the Publishable key (
pk_live_…). - Create a Restricted key or use the Secret key (
sk_live_…). Keep it private.
Activate Stripe in WHMCS
- Go to Configuration → System Settings → Payment Gateways.
- Under All Payment Gateways, click Stripe and activate it.
- Enter the Stripe Publishable API Key and Stripe Secret API Key.
- Set the Display Name, for example
Credit / Debit Card. - Leave Webhook Endpoint Secret for the next step.
- Click Save Changes.
Add the webhook
Recent WHMCS versions create the webhook automatically when you save the keys. If not, in Stripe go to Developers → Webhooks → Add endpoint, enter https://billing.example.com/modules/gateways/callback/stripe.php, select the events WHMCS lists in its documentation (such as payment_intent.succeeded and charge.refunded), and copy the Signing secret into WHMCS's Webhook Endpoint Secret.
How recurring charges work
- When a client pays the first invoice by card, Stripe stores the card and WHMCS saves a token as a pay method on the client profile.
- On renewal, the daily cron attempts the charge according to Process Credit Card Charges in Automation Settings.
- If 3D Secure is required, the client gets an email asking them to authorise the payment.
- Failed charges send the Credit Card Payment Failed email and retry on the days you configure.
Test first
Enter Stripe's test keys (pk_test_…, sk_test_…), place an order and pay with Stripe's test card 4242 4242 4242 4242. Confirm the invoice is paid and the token is saved under the client's Pay Methods. Then switch back to live keys.
Refunds
Open the invoice in WHMCS, go to the Refund tab, choose the transaction and Refund through Gateway. WHMCS sends the refund to Stripe and records it, keeping both systems in sync.
Troubleshooting
- "No such token" or invalid key: mixing test and live keys. Use a matching pair.
- Payments succeed at Stripe but invoices stay unpaid: webhook not configured or signing secret wrong. Check Billing → Gateway Log and Stripe's webhook attempts.
- Renewals not charged: the cron did not run, the client has no stored card, or automatic capture is disabled on the client profile (Disable Automatic CC Processing).
- Many declines from one country: enable Stripe Radar rules and keep CAPTCHA on checkout to stop card testing.