WHMCS PayPal integration today means the PayPal Payments module, which ships with WHMCS and connects your PayPal account through a login and consent screen, not pasted API keys. Activating it also turns on PayPal Card Payments for unbranded cards. PayPal Basic and PayPal Checkout, the modules that create PayPal Subscriptions, are deprecated, and WHMCS can move their clients over to PayPal Payments.
Which PayPal module should you use in WHMCS?
Use PayPal Payments. WHMCS ships seven PayPal modules, and its Accepting PayPal page marks all of them deprecated except PayPal Payments and its companion, PayPal Card Payments. All seven take one-time and recurring payments and refunds. They differ in how they store payment details and what WHMCS can track.
| Module | Status | Type | PayPal Subscriptions | Reversals in WHMCS | Disputes in WHMCS |
|---|---|---|---|---|---|
| PayPal Payments | Recommended | Token | No | Yes | Yes |
| PayPal Card Payments | Recommended, activates with PayPal Payments | Token | No | Yes | Yes |
| PayPal Checkout | Deprecated | Third-party | Yes | No | Yes |
| PayPal Basic | Deprecated | Third-party | Yes | Yes | No |
| PayPal Pro Reference Payments | Deprecated | Token | No | No | No |
| PayPal Website Payments Pro | Deprecated | Merchant | No | No | No |
| PayFlow Pro | Deprecated | Merchant | No | No | No |
The type column matters. A token gateway keeps a reference to the payment method at PayPal, a third-party gateway sends the client to PayPal to pay, and a merchant gateway stores card details in the WHMCS database, which puts card data in your PCI scope. PayPal Basic is not available on WHMCS Cloud.
Do you need PayPal API credentials or only an email address?
For PayPal Payments you need neither. You click Link PayPal Account, log in, approve the WHMCS application, and WHMCS saves the API credentials itself. PayPal Checkout links the same way.
PayPal Basic is the module that runs on an email address. Its only required field is PayPal Email, which takes one or more comma-separated addresses. The optional API Username, API Password and API Signature, created under NVP/SOAP API integration (Classic) in PayPal, let you refund from inside WHMCS. When the receiver of a payment does not match that list, you get an Invalid Receiver error.
How do you set up PayPal Payments in WHMCS?
Activate it from Apps & Integrations, link the account and switch off test mode. These are the steps on the PayPal Payments page, in order:
- Make sure the WHMCS System URL begins with
https://and the SSL certificate is valid. Without both, PayPal will not connect. - Disable the PHP OPcache extension. WHMCS will not activate PayPal Payments while OPcache is on.
- Go to Configuration > Apps & Integrations, choose the Payments category and click Activate & Configure for PayPal Payments. This activates PayPal Card Payments too.
- Click Link PayPal Account, log in, accept the permission screen and click Confirm.
- Tick Show on Order Form and, if you like, change the Display Name.
- Untick Test Mode, which is on by default, and click Save Changes.
PayPal Card Payments then appears at Configuration > System Settings > Payment Gateways as Credit/Debit Cards, on the same linked account. It can show only while PayPal Payments shows, and it cannot be activated where PayPal does not fully support Advanced Cards. Saved methods depend on PayPal Vault, which covers the merchant countries the module page lists. Without Vault, you may still be able to take one-time payments.
How do PayPal subscriptions work in WHMCS?
Only the deprecated PayPal Basic and PayPal Checkout modules create PayPal Subscriptions. PayPal Payments supports recurring payments another way: the client's PayPal account or card is stored in PayPal Vault and used again for later payments, so renewals follow WHMCS invoices rather than a PayPal subscription schedule.
On PayPal Basic, a Subscribe option appears on an invoice only when:
- the invoice due date is in the future;
- the invoice contains at least one recurring product, because invoices holding only domains, billable items or product addons do not qualify;
- Force One Time Payments is not ticked in the module settings.
Addons and domains on the same invoice join the subscription only if they renew on the product's cycle, and one subscription cannot combine a monthly amount with an annual one. PayPal Checkout offers a subscription for monthly and annual products and has no setting to force one-time payments.
When PayPal Payments is active next to PayPal Basic or PayPal Checkout, WHMCS preselects PayPal Payments on their invoices and moves a client's old subscription to vaulting the first time that client pays with PayPal. PayPal may then email the client about a canceled subscription, which the documentation says is expected. Keep the old modules activated so the move can happen, but untick Show on Order Form on each. Never click Unlink PayPal Account on a module with live subscriptions: it cannot be undone, and WHMCS stops recording those payments.
Does WHMCS use PayPal IPN or webhooks?
PayPal Basic uses IPN, and PayPal Payments uses a webhook registered on the WHMCS app in PayPal. Both break when the WHMCS address changes.
- IPN for PayPal Basic. In PayPal, open Account Settings, then Notifications, and update Instant Payment Notifications. Enter your WHMCS System URL, select Receive IPN messages (Enabled) and save. Set the account's language encoding to UTF-8; the windows-1252 default can break accented characters and cause IPN Handshake Invalid.
- Webhook for PayPal Payments. The address ends in
/modules/gateways/callback/paypalwebhooks.php. After a move, log in to the PayPal Developer Portal, select Live, open the WHMCS app, edit the URL under Live Webhooks and save.
For IPN after a move, the PayPal IPN Failures page offers a redirect: upload the paypal.php it provides to the old callback path, with $url set to the new location. PayPal retries a failed IPN between four hours and four days later, and once the fault is fixed WHMCS records the payment by itself. Both callbacks are on my checklist for every WHMCS migration.
How do you refund a PayPal payment from WHMCS?
Open the invoice's Refund tab, pick the transaction and choose Refund through Gateway; the money goes back to the method the client used. The other two types move no money: Manual Refund Processed Externally records a refund you make in PayPal, and Add to Client's Credit Balance gives account credit. Rules from the Invoice Management page:
- One transaction at a time, never more than its amount.
- A refund on a Paid invoice creates a credit note.
- A full refund reverses any affiliate commission on the payment. A partial refund asks whether to reverse it, and the reversal is all or nothing.
- PayPal Basic needs its API credentials filled in to refund through the gateway.
Disputes for PayPal Payments, PayPal Card Payments and PayPal Checkout appear at Billing > Disputes.
How do you test WHMCS PayPal in sandbox mode?
Link a PayPal sandbox account next to the live one and keep Test Mode ticked. At Configuration > System Settings > Payment Gateways, click Link Sandbox Account under PayPal Payments, log in to a sandbox account, confirm and save. On PayPal Basic, sandbox API credentials that differ from the live ones have to be swapped in and back by hand. On a staging copy with a public HTTPS address, I then run:
- One invoice paid with the PayPal button and one with the card option.
- A monthly order with a saved method, then its renewal invoice.
- One refund through the gateway, checking the credit note and Gateway Log.
- One small live payment after unticking Test Mode, refunded afterwards.
Why is WHMCS PayPal not working?
Start at Billing > Gateway Log and the Module Log, then match the message below. Each row comes from the WHMCS PayPal troubleshooting pages, such as Missing PayPal Payments.
| What you see | Documented cause | What to do |
|---|---|---|
| Paid in PayPal, invoice unpaid, Signature Verification Failed in the log | The payment came from a subscription made under another linked app, often after Unlink PayPal Account | Cancel those subscriptions in PayPal; clients subscribe again on the next invoice |
| An unknown error occurred. Please try again | WHMCS sent invalid client data, such as an empty country code | Read the Module Debug Log, then fix the client profile or billing contact |
| IPN failure email or IPN Handshake Invalid | Site offline, a moved URL, or the windows-1252 charset | Fix the site, update the URL, set the charset to UTF-8 |
| IPN Handshake Error | WHMCS could not verify the IPN, usually a cURL problem; PayPal requires TLS 1.2 and HTTP/1.1 | Run curl -I https://www.paypal.com/cgi-bin/webscr on the server |
DUPLICATE_INVOICE_ID | One PayPal account serves several systems with Block accidental payments on | Choose No, allow multiple payments per invoice ID |
L_SHORTMESSAGE0 => Security error | The API details in the module are invalid | Generate and enter the credentials again |
| Invalid Receiver, Not Supported or Unrecognized Currency | The payment receiver value does not match the WHMCS configuration | Check the PayPal Email list and the invoice currency |
| Referenced transaction or order is too old | The transaction is more than 24 months old | Handle it in PayPal directly |
Transaction ID X already exists is harmless. For a currency PayPal's API rejects, the documented workaround is the deprecated PayPal Basic with Convert To For Processing; I would rather bill in a supported currency.
What are the limits of PayPal in WHMCS?
- No PayPal Subscriptions on the recommended module. Only deprecated modules offer them.
- Country rules. Saved methods need PayPal Vault and the card option needs Advanced Cards. Both depend on your merchant country.
- OPcache off. The activation requirement can clash with how a host tunes PHP, so agree it with the host first.
- Deprecated modules. They still run, but new setups should not start on them.
- Card-first customers. If most clients pay by card rather than with a PayPal account, compare Stripe in WHMCS, which stores cards and handles 3D Secure differently.
PayPal flows the shipped modules do not cover, such as a custom checkout or syncing PayPal data with another system, are work I take on under WHMCS payment gateway integration.
Last reviewed 12 October 2026. Disclosure: I sell WHMCS and web development work, 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 errors come from the WHMCS 9.0 documentation as I read it on that date.
