The PayPal® Basic payment gateway module is available in WHMCS.

Supported Features #

Type: Third-Party

Adding the PayPal Basic Payment Gateway #

To set up the PayPal Basic payment gateway in WHMCS:

1. Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
2. Click PayPal Basic.
3. Check Show on Order Form to display this payment method in the Client Area during checkout.
4. Enter your PayPal Basic credentials. PayPal Email is required and all other values are optional.
   1. For PayPal Email, enter one or more email addresses associated with your PayPal account, comma-delimited.
   2. Configure Instant Payment Notification using the steps below.
   3. 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.
   4. Check Force Subscriptions to only allow clients to make subscription payments (disabling one-time payments). The system will send future payments automatically.
   5. 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.
   6. 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.
   7. For API Username, API Password, and API Signature, enter your PayPal account’s credentials:
      1. Log in to your PayPal account.
      2. Go to Account Settings by hovering over your name in the top-right corner.
      3. Click Update next to API Access.
      4. Under NVP/SOAP API integration, click Manage API credentials.
      5. Choose Request API signature.
      6. 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.
5. 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:

1. Log in to your PayPal account.
2. Click the settings icon (usually your name) at the top of your PayPal account page.
3. Click Account Settings.
4. Select Notifications on the left-hand menu.
5. Click Update for Instant Payment Notifications.
6. Click Choose IPN Settings (or Edit Settings if it is already enabled).
7. Enter your WHMCS System URL (for example, https://www.example.com/whmcspath/).
8. Select Receive IPN messages (Enabled).
9. 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:

1. Go to PayPal’s Language Encoding.
2. Click More Options.
3. Select a charset. The default value in WHMCS is UTF-8.
4. Select Yes.
5. Click Save.

PayPal Subscriptions/Recurring Billing #

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:

1. The invoice’s Due Date must be in the future.
2. 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).
3. 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.

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:

1. Log in to PayPal.
2. Go to Tools > All Tools > API credentials > NVP/SOAP API integration (Classic).
3. Click Manage API Credentials under NVP/SOAP API integration (Classic).
4. Generate a new set of credentials or note the current credentials.
5. Copy the provided username, password, and signature.
6. Click Done.
7. 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:

Last modified: January 30, 2025