WHMCS PayPal Integration: Setup, Subscriptions & Troubleshooting

PayPal isn't optional even when you have Stripe. Some customers refuse to enter card details and only pay through PayPal. Some regions (especially Europe) have higher PayPal acceptance than Stripe. Running both is the standard, and the configuration trips people up in specific ways.

This is the PayPal setup that works in production.

Step 1 — Pick the right PayPal module

WHMCS ships three PayPal-related modules:

• PayPal (Standard) — legacy. Redirects to PayPal, customer pays, returns. Subscriptions partially supported. Avoid for new installs.
• PayPal Smart Buttons / Checkout — current. Uses PayPal's modern checkout flow with embedded buttons. Supports billing agreements (recurring).
• PayPal Subscriptions — for SaaS-style recurring where PayPal owns the subscription cycle.

For hosting (WHMCS-managed recurring renewals), use PayPal Checkout / Smart Buttons. WHMCS bills the customer; PayPal charges; renewals work because WHMCS stores a billing agreement.

Step 2 — Set up the PayPal business account properly

1. Sign up at paypal.com/business (not personal).
2. Verify your business: tax ID, bank account, ID documents.
3. Activate the relevant APIs — Settings → Business profile → Information & preferences.
4. Confirm you can accept the currencies you bill in (PayPal limits some currency combinations).

Step 3 — Create API credentials

1. Go to developer.paypal.com, log in.
2. My Apps & Credentials → Live → Create App.
3. Name the app (e.g., "WHMCS-prod"), select your business account.
4. Pick features: Checkout, Vault (saved billing agreements), Subscriptions if you need them.
5. Copy the Client ID + Client Secret.

Also create a Sandbox app — same flow but in Sandbox mode. Use this for testing.

Step 4 — Configure WHMCS PayPal module

WHMCS Admin → Setup → Payments → Payment Gateways → All Payment Gateways → PayPal Checkout → Activate.

• Display Name: "PayPal" — keep it simple.
• Client ID: from PayPal Developer (Live).
• Client Secret: same.
• Account Mode: Live (not Sandbox — only Sandbox for testing).
• Use IPN: yes. (See webhook section below.)
• Convert To For Processing: leave blank unless you need currency conversion.
• Subscriptions: enable if you want recurring billing agreements stored.

Save. Confirm the gateway appears in active list with no errors.

Step 5 — IPN / webhook — the part that's always forgotten

PayPal sends payment notifications via IPN (Instant Payment Notification) or webhooks. Without it, refunds and disputes don't sync to WHMCS.

For IPN:

1. PayPal Business Account → Settings → Notifications → IPN (Instant Payment Notification).
2. Enable IPN.
3. Notification URL: https://yourwhmcs.com/modules/gateways/callback/paypal.php (or whichever PayPal module you're using).

For modern PayPal webhooks (Vault, Subscriptions):

1. Developer Dashboard → My Apps → your app → Webhooks.
2. Add webhook URL.
3. Subscribe to events: PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED, BILLING.SUBSCRIPTION.CANCELLED, CUSTOMER.DISPUTE.CREATED.

Step 6 — Test the full cycle

Use Sandbox accounts (PayPal Developer → Sandbox → Accounts) — fake buyer + seller accounts that simulate real PayPal flows.

1. Place a test order in WHMCS.
2. At checkout, pick PayPal. Click the PayPal button.
3. Pay using the Sandbox buyer account.
4. Confirm the invoice marks paid in WHMCS within seconds.
5. Refund the test transaction from PayPal Sandbox dashboard.
6. Within 30-60 seconds, WHMCS invoice marks refunded.
7. Test a recurring renewal — fast-forward a hosting due date, run cron, watch for the billing-agreement charge.

Common pitfalls

"Payment shows in PayPal but invoice stays unpaid in WHMCS." IPN/webhook not configured or being blocked. Most common: WAF blocks PayPal's IPs. Whitelist them or relax WAF on the callback URL.

"PayPal button doesn't render on checkout." Client ID is wrong, or in Sandbox mode while WHMCS is configured for Live. Match the modes.

"Recurring subscriptions fail after first payment." WHMCS isn't storing the billing agreement. Confirm the Vault feature is enabled on your PayPal app + WHMCS module config.

"Customers see PayPal in their language but WHMCS in another." PayPal auto-detects locale; WHMCS uses its own. Pass locale param to the PayPal button if you want consistency.

"Currency conversion issues." PayPal converts at its rates if buyer's currency differs from yours. Either accept the conversion fee or restrict customer choice. Most operators just accept the fee.

My take — PayPal vs Stripe per region

For US/UK customers: Stripe wins (lower fees, smoother UX). For Europe (especially DE, NL, FR): PayPal acceptance is high. For emerging markets: pair PayPal with a regional gateway (Razorpay for India, MercadoPago for LATAM, etc.).

I always run Stripe + PayPal + one regional gateway. Coverage of 95%+ customer preferences with three gateways.

Going further

• PayPal Checkout docs
• WHMCS PayPal module docs
• My Stripe integration guide — pair both.

I set up PayPal + Stripe + regional gateways for hosting businesses. If your payment stack isn't smooth, tell me what's broken and I'll send a quote in 24 hours.