WHMCS Stripe Integration: Complete Payment Gateway Setup Guide

Stripe is the gold standard for online payments, powering millions of businesses worldwide. Integrating Stripe with WHMCS gives your customers a seamless checkout experience with support for cards, digital wallets, and recurring subscriptions. This guide covers everything from basic setup to advanced optimizations.

Prerequisites

Before you begin, ensure you have:

• WHMCS 8.0 or later installed
• Valid SSL certificate on your WHMCS installation
• Stripe account (sign up at stripe.com)
• Verified Stripe business identity

Step 1: Get Your Stripe API Keys

1. Log in to your Stripe Dashboard
2. Navigate to Developers → API Keys
3. Copy your Publishable key (starts with pk_)
4. Click "Reveal test key" to get your Secret key (starts with sk_)

Step 2: Configure Stripe in WHMCS

1. In WHMCS Admin, go to Setup → Payments → Payment Gateways
2. Click All Payment Gateways tab
3. Find and click Stripe
4. Enter your API credentials:
   • Publishable Key
   • Secret Key
5. Configure additional options (covered below)
6. Click Save Changes

Step 3: Configure Webhooks

Webhooks are essential for Stripe to notify WHMCS about payment events like successful charges, failed payments, and subscription renewals.

Create Webhook Endpoint

1. In Stripe Dashboard, go to Developers → Webhooks
2. Click Add endpoint
3. Enter your webhook URL: https://yourdomain.com/modules/gateways/callback/stripe.php
4. Select events to listen for:
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • invoice.payment_succeeded
   • invoice.payment_failed
   • customer.subscription.deleted
   • charge.refunded
5. Click Add endpoint
6. Copy the Signing secret

Add Webhook Secret to WHMCS

In WHMCS Stripe gateway settings, paste the webhook signing secret in the Webhook Endpoint Secret field.

Enabling Payment Methods

Stripe supports multiple payment methods. Configure these in your Stripe Dashboard:

Digital Wallets

• Apple Pay: Verify your domain in Stripe Dashboard
• Google Pay: Enabled by default with card payments
• Link: Stripe's one-click checkout

Alternative Payment Methods

Enable these in Stripe Dashboard → Settings → Payment methods:

• SEPA Direct Debit (Europe)
• iDEAL (Netherlands)
• Bancontact (Belgium)
• BACS Direct Debit (UK)
• ACH Direct Debit (US)

3D Secure (SCA) Configuration

3D Secure is required for European transactions under SCA regulations. WHMCS's Stripe integration handles this automatically, but ensure:

• Your Stripe integration uses Payment Intents (default in WHMCS 8+)
• Webhooks are properly configured
• Your checkout page supports the 3DS authentication popup

Subscription/Token Billing Setup

For recurring billing, configure token billing in WHMCS:

1. Go to Setup → Payments → Payment Gateways → Stripe
2. Set Credit Card Storage to "Yes"
3. Choose token billing behavior:
   • Always: Tokenize all transactions
   • Optional: Let customer choose
   • Never: Don't store cards (not recommended)

Optimizing Conversion Rates

Maximize successful payments with these optimizations:

Enable Stripe Radar

Stripe's machine learning fraud detection. Configure in Stripe Dashboard:

• Enable Radar for Fraud Teams if available
• Set up custom rules based on your risk tolerance
• Review blocked transactions regularly

Smart Retries

Configure retry logic in WHMCS:

• Go to Setup → Automation Settings
• Enable Retry on Payment Failure
• Set appropriate retry intervals (1, 3, 7 days)

Customer Portal Card Updates

Allow customers to update expired cards:

• Customers can update cards in Client Area → Billing
• Send expiry reminder emails before cards expire
• Use Stripe's automatic card updater (enabled by default)

Testing Your Integration

Use Stripe's test card numbers to verify your setup:

Going Live

Once testing is complete:

1. Complete Stripe identity verification if not done
2. Replace test API keys with live keys
3. Create a new webhook endpoint with your live endpoint secret
4. Test with a small real transaction
5. Monitor your first few days of transactions closely

Troubleshooting Common Issues

Payments Not Processing

• Verify API keys are correct (test vs. live)
• Check WHMCS module log for errors
• Ensure SSL certificate is valid

Webhooks Failing

• Verify webhook URL is accessible
• Check webhook signing secret matches
• Review webhook logs in Stripe Dashboard

3D Secure Issues

• Ensure WHMCS is updated to latest version
• Check for JavaScript errors on checkout page
• Test with 3DS-required test cards

Conclusion

Stripe integration with WHMCS provides a world-class payment experience for your customers. With proper configuration of webhooks, 3D Secure, and token billing, you'll minimize payment failures and maximize revenue. Regular monitoring of your Stripe Dashboard helps catch issues before they impact your business.