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 #

Invalid Receiver Email #

WHMCS validates the payment receiver email value against the details at Configuration () > System Settings > Payment Gateways. This error indicates that the details do not match.

If you use multiple PayPal accounts to receive payment or a single PayPal account has multiple email addresses, you must specify them in a comma-separated list (for example, [email protected],[email protected]).

The system will use the first email in the list for new payments but will accept any email address for invoice payments.

Not Supported #

This error indicates that an action occurred that does not require any action from WHMCS. For example, a txn_type value of subscr_failed indicates that a subscription payment failed, and subscr_eot indicates the end of the subscription term.

You will see these entries under normal operation and they do not indicate a problem.

Unrecognized Currency #

This error in the Gateway Log indicates an invalid currency code in Configuration () > System Settings > Currencies.

A currency code must use the ISO 4217 standard. For example, EURO is not valid, but EUR is valid.

IPN Handshake Invalid #

This error in the Gateway Log indicates that WHMCS cannot verify that the callback is from PayPal. To correct this issue, check your Charset Configuration.

IPN Handshake Error #

This error in the Gateway Log indicates that the system received the IPN from PayPal but could not verify it. Typically, this occurs because connection to PayPal’s callback verification service at https://www.paypal.com/cgi-bin/webscr failed, usually because the cURL connection does not use the required protocols. TLS 1.2 and HTTP/1.1 are mandatory for communication with PayPal.

The WHMCS PayPal module does not specify a particular cryptographic protocol when communicating with PayPal. Instead, cURL on your server should automatically negotiate the best protocol to use. Work with your hosting provider or system administrator to ensure TLS 1.2 or greater is the default protocol on the server and that you can successfully connect to PayPal’s callback verification service.

You can check connection using cURL from your servers command line:

curl -I https://www.paypal.com/cgi-bin/webscr

Things don’t appear to be working at the moment #

This error indicates that your system has sent invalid details to PayPal. This could be invalid client details (for example, the address or postcode) or a misconfiguration in the WHMCS settings (for example, an invalid currency code).

To troubleshoot this issue, view the page source in the Client Area and examine the PayPal payment button HTML code. Look for any invalid variables and edit the client’s profile or the system settings to correct them.

If the currency_code value is not in the PayPal API’s supported currency list, you can use Convert to For Processing to convert the payment amount into a currency that PayPal supports.

Last modified: December 23, 2024