PayPal Basic
We deprecated this module in WHMCS 8.11.
- In WHMCS 8.9 and later, we strongly recommend using the PayPal Payments payment gateway module instead.
- In WHMCS 8.11 and later, if PayPal Payments and PayPal Basic are both enabled, WHMCS will transition PayPal Basic invoices and subscriptions to use PayPal Payments as the preselected payment method.
- Do not deactivate PayPal Basic if you want to use this method to migrate to PayPal Payments.
- For more information, see Automated Transition from Legacy PayPal Modules and Unexpected PayPal Cancellation Emails.
The PayPal® Basic payment gateway module is available in WHMCS.
Supported Features
Type: Third-Party
One-Time | Recurring | Refunds | Reversals |
✓ | ✓ | ✓ | ✓ |
3D Secure | Remote Update Card | Remote Delete Card | AddPayMethod API |
✖️ | ✖️ | ✖️ | ✖️ |
Adding the PayPal Basic Payment Gateway
To set up the PayPal Basic payment gateway in WHMCS:
- Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
- Click PayPal Basic.
- Check Show on Order Form to display this payment method in the Client Area during checkout.
- Enter your PayPal Basic credentials. PayPal Email is required and all other values are optional.
- For PayPal Email, enter one or more email addresses associated with your PayPal account, comma-delimited.
- Configure Instant Payment Notification using the steps below.
- Check Force One Time Payments to only allow clients to make one-time payments (disabling subscriptions). For recurring services, clients must log in and pay each invoice.
- Check Force Subscriptions to only allow clients to make subscription payments (disabling one-time payments). The system will send future payments automatically.
- Check Require Shipping Address to require clients to provide a shipping address on the PayPal website to associate with their payment at PayPal. We recommend this if you are selling physical products or require PayPal Seller Protection.
- Check Client Address Matching to associate the details that the client provides while ordering with their payment in PayPal. They will not be able to provide different detals on the PayPal website and must update their details from within the Client Area. Alternately, you can update client details in the Profile tab of the client profile.
- For API Username, API Password, and API Signature, enter your PayPal account’s credentials:
- Log in to your PayPal account.
- Go to Account Settings by hovering over your name in the top-right corner.
- Click Update next to API Access.
- Under NVP/SOAP API integration, click Manage API credentials.
- Choose Request API signature.
- Click Agree and Submit.This allows you to issue refunds from within WHMCS instead of logging in via PayPal. For more information, see Automated Refunds.
- Click Save Changes.
Sandbox Mode
You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful for testing your configuration.
- To use this, you must create a PayPal sandbox account.
- If your sandbox API credentials differ from your live account’s, you must update them in your configuration and reset them when you finish testing.
Instant Payment Notification
When you enable Instant Payment Notification (IPN) in your PayPal account, the system will automatically mark invoices as paid when you receive payments.
To enable IPN:
- Log in to your PayPal account.
- Click the settings icon (usually your name) at the top of your PayPal account page.
- Click Account Settings.
- Select Notifications on the left-hand menu.
- Click Update for Instant Payment Notifications.
- Click Choose IPN Settings (or Edit Settings if it is already enabled).
- Enter your WHMCS System URL (for example,
https://www.example.com/whmcspath/
). - Select Receive IPN messages (Enabled).
- Click Save.
Charset Configuration
PayPal defaults the charset for most accounts to windows-1252
. Occasionally, this can cause accented characters to return incorrectly through IPN, causing an IPN Handshake Invalid message. Because of this, we strongly recommend that you set the charset in your PayPal account to match your WHMCS installation.
To change the charset:
- Go to PayPal’s Language Encoding.
- Click More Options.
- Select a charset. The default value in WHMCS is
UTF-8
. - Select Yes.
- Click Save.
PayPal Subscriptions/Recurring Billing
- In WHMCS 8.11 GA and later, if you have activated PayPal Payments, WHMCS will automatically transition a client’s PayPal Basic subscriptions to use vaulting with PayPal Payments the first time that the client uses PayPal to make a payment.
- When WHMCS transitions a client’s subscriptions, the client may receive a notification from PayPal about the subscription cancellation. PayPal sends this email to your client automatically, but it does not indicate a problem. For more information, see Unexpected PayPal Cancellation Emails.
By default, when a user views an invoice for a recurring product or service, a PayPal Subscribe option will appear. This allows the user to subscribe and send automatic payments on the appropriate billing society.
Invoices are eligible for subscriptions if they meet all of the following conditions:
- The invoice’s Due Date must be in the future.
- The invoice must contain at least one recurring product (for example, invoices that only contain domains, billable items, or product addons won’t create subscriptions).
- Force One Time Payments is not checked on the payment gateway configuration page.
If an invoice contains a product and product addons or domains, any items that match the product’s billing cycle will also be part of the subscription. For example, if an invoice contains a product, a product addon, and a domain that all recur on an annual basis, the PayPal subscription that WHMCS creates would be for the total amount of all three items. The subscription amount would pay the renewal invoice in full automatically.
Subscriptions cannot, however, contain different amounts recurring on different terms. For example, a single subscription cannot create recurring payments of one amount monthly and another amount annually.
Customizing Invoice Emails for Subscriptions
WHMCS stores the PayPal-issued subscription ID number as Subscription ID for the product and removes it when cancelling the subscription. Because of this, you can use the ID value to determine whether a subscription exists and customize the displayed text in invoice-related emails.
For example, you could customize the Invoice Created email template to show different instructions to the customer if a subscription exists:
{if $invoice_subscription_id}
As you have a PayPal Subscription setup, payment will be taken automatically within the
next few days. Make certain that you have enough funds in your PayPal account to cover it.
{else}
You can login to your Client Area to view and pay the invoice at {$invoice_link}
{/if}
Automatic Subscription Management
If you enable Automatic Subscription Management, WHMCS will attempt to automatically cancel PayPal subscriptions.
For more information, see Automatic Subscription Management.
Automated Refunds
You can issue refunds for PayPal payments directly from within WHMCS. Before you can do this, you must set up PayPal API access.
To do this:
- Log in to PayPal.
- Go to Tools > All Tools > API credentials > NVP/SOAP API integration (Classic).
- Click Manage API Credentials under NVP/SOAP API integration (Classic).
- Generate a new set of credentials or note the current credentials.
- Copy the provided username, password, and signature.
- Click Done.
- Enter the details at Configuration () > System Settings > Payment Gateways.
Troubleshooting
You can find information about most payment gateway-related errors in the logs at Billing > Gateway Log and in the Module Log.
You may encounter the following common issues when using PayPal payment gateways:
Error or Issue | Cause | Next Steps |
DUPLICATE_INVOICE_ID | Your PayPal® configuration is blocking the transaction. | Duplicate Invoice ID Errors |
A payment successfully deposits to your PayPal® account but does not appear in WHMCS. | This problem can occur due to several different issues. | Missing PayPal Payments |
The system has detected a missing subscription. The subscription is not associated with any services, but the event was attributable to a client and/or invoice. | The subscription is not associated with any service, product addon, or domain but the system found an alternate ID to use. | Missing PayPal Subscriptions |
You are experiencing problems that relate to stale cached data or PHP script execution. | The OPcache PHP extension is enabled. | OPcache Warnings |
The system has detected an orphaned subscription. It is not associated with any services, nor was attributable to an invoice or client. | The subscription is not associated with any service, product addon, or domain and the system could not find an alternate ID to use. | Orphaned PayPal Subscriptions |
No Local Credit Card Payment Gateways Enabled | You disabled the option to save card details for later. | PayFlow Pro Local Card Errors |
Details could not be saved. Remote storage failed | You attempted to create a payment method. | PayFlow Pro Remote Storage Errors |
You receive an email stating that a PayPal® Instant Payment Notification (IPN) failed or you see IPN Handshake Invalid or IPN Handshake Error error messages. | PayPal could not send a payment notification to your WHMCS installation or WHMCS cannot verify a callback. | PayPal IPN Failures |
The system has detected an orphaned subscription. It is not associated with any services, nor was attributable to an invoice or client. or The system has detected a missing subscription. The subscription is not associated with any services, but the event was attributable to a client and/or invoice. | The subscription is not associated with any service, addon, or domain. | PayPal Log Entries |
Referenced transaction or order is too old | The transaction is more than 24 months old. | PayPal Old Transaction Errors |
You are experiencing problems with subscriptions after attempting to migrate to PayPal Payments while using WHMCS 8.9 through 8.11 RC. | WHMCS 8.9 through 8.11 RC do not support migrating from another PayPal gateway to PayPal Payments if you process any recurring payments through PayPal. | PayPal Payments Issues |
L_SHORTMESSAGE0 => Security error | The API details in your PayPal® payment gateway configuration are invalid. | PayPal Security Errors |
The system will not connect to PayPal® correctly. | Some PayPal payment gateway modules require an HTTPS-secured connection. | PayPal SSL Errors |
Transaction ID X already exists | This log entry does not indicate a problem. You can safely ignore it. | PayPal Transaction ID Errors |
You receive an Invalid Receiver email. | The payment receiver value does not match your PayPal® configuration in WHMCS. | PayPal® Invalid Receiver Errors |
Not Supported | The payment receiver value does not match your PayPal® configuration in WHMCS. | PayPal® Not Supported Errors |
Things don't appear to be working at the moment | Your system has sent invalid details to PayPal®. | PayPal® Not Working Errors |
Unrecognized Currency | The payment receiver value does not match your PayPal® configuration in WHMCS. | PayPal® Unrecognized Currency Errors |
Your customers are receiving notification emails from PayPal® about a subscription cancellation after they make a payment. | WHMCS must cancel PayPal Basic and PayPal Checkout subscriptions to transition them to PayPal Payments. | Unexpected PayPal Cancellation Emails |
Last modified: January 30, 2025