PayPal Payments

We added this payment gateway in WHMCS 8.9 and strongly recommend it for all new PayPal® merchants.
If you enabled this module while using the Beta release of WHMCS 8.9, you must reactivate the module before using it with WHMCS 8.9 Release Candidate or later. If you do not do this, you may experience problems.

PayPal Payments uses PayPal’s latest secure tokenization system. It ensures the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault, now available for PayPal merchant accounts in merchant-supported countries.

When you use PayPal Payments, clients can make one-click payments, including payment with credit and debit cards, during checkout and on invoices. Activating PayPal Payments also activates the PayPal Card Payments module, giving you the choice to display a separate unbranded option that accepts credit and debit cards.

WHMCS includes several options for accepting payments through PayPal. For more information, see Accepting PayPal.

Supported Features

Type: Token

One-TimeRecurringRefundsReversals
3D SecureRemote Update CardRemote Delete CardAddPayMethod API
✖️✖️

Adding the PayPal Payments Payment Gateway

To set up the PayPal Payments payment gateway in WHMCS:

  1. Ensure that your WHMCS installation uses an HTTPS-secured connection with a valid SSL certificate.
    This module requires an HTTPS-secured connection. If the WHMCS installation’s domain does not have a valid SSL certificate or the WHMCS System URL value does not begin with https://, the connection between WHMCS and PayPal will not work.
  2. Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
  3. Choose the Payments category in the left-side menu.
  4. Click Activate & Configure for PayPal Payments. This will also activate PayPal Card Payments.
  5. Click Link PayPal Account to begin accepting payments with PayPal.
    To link a sandbox account for testing purposes, see Test Mode below.
  6. Log in to your chosen PayPal account or sign up for a new one.
  7. Confirm permission for the WHMCS application to access your account.
  8. Click Confirm to continue. API credentials will populate and WHMCS will save them automatically. Then, the page will refresh.
  9. Check Show on Order Form to display this payment method in the Client Area during checkout.
    You cannot disable Show on Order Form for PayPal Payments if Show on Order Form is enabled for PayPal Card Payments.
  10. Optionally, enter a new display name for Display Name.
  • By default, this module uses PayPal as the display name in the Client Area.
  • You will see the name that you enter here when you configure the payment gateway at Configuration () > System Settings > Payment Gateways.
  1. Uncheck Test Mode.
    We enable Test Mode by default for this payment gateway.
  2. Click Save Changes.
For a step-by-step walkthrough of the setup process, see Configure PayPal Payments.

Test 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. Using test mode requires linking a separate PayPal Sandbox account to your WHMCS installation in addition to your live PayPal merchant account.

To do this:

  1. Go to Configuration () > System Settings > Payment Gateways.
  2. Find the PayPal Payments module and click Link Sandbox Account.
  3. Log in to your existing PayPal sandbox account or create a new PayPal sandbox account.
  4. Confirm permission for the WHMCS application to access your account.
  5. Click Confirm to continue. API credentials will populate and WHMCS will save them automatically.
  6. Ensure that Test Mode is enabled.
  7. Click Save Changes.

PayPal Card Payments

When you activate PayPal Payments, WHMCS also automatically activates PayPal Card Payments. This module augments PayPal Payments, allowing you an unbranded option for credit and debit card payments that is visualy separate from the PayPal checkout experience.

  • This module uses the PayPal account settings that you configure for PayPal Payments.
  • You cannot display PayPal Card Payments unbranded options during checkout without also displaying the PayPal-branded option from the PayPal Payments module.
  • You cannot deactivate the PayPal Payments module without first deactivating the PayPal Card Payments module.
If PayPal does not fully support PayPal Advanced Cards for your country or region, you cannot activate PayPal Card Payments. However, if you activate PayPal Payments, a Credit/Debit Card option for one-time payments will display with the PayPal option in the Client Area.

To set up the PayPal Card Payments payment gateway in WHMCS:

  1. Activate and configure the PayPal Payments module (above).
  2. Go to Configuration () > System Settings > Payment Gateways.
  3. Find the PayPal Card Payments module in the list of active gateways. By default, this module uses Credit/Debit Cards as the display name here and in the Client Area.
  4. Check Show on Order Form to display this payment method in the Client Area during checkout.
    You cannot enable Show on Order Form for this module without first enabling Show on Order Form for the PayPal Payments module.
  5. Optionally, enter a new display name for Display Name.
  6. Click Save Changes.

Vaulting

In PayPal-supported countries, the PayPal Payments and PayPal Card Payments modules ensure the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault.

  • When clients pay using PayPal Payments, PayPal will attempt to store the pay method automatically.
  • When clients pay using PayPal Card Payments, a Save card for faster checkout in future option will display while entering credit card details.
    • Selecting this option causes PayPal to attempt to add the card to PayPal Vault.
    • This option is not available in the Admin Area.
  • Unlike previous PayPal payment gateways, this module stores encrypted vaulted data locally.

After PayPal successfully stores a payment method, it will be available for the client when they pay an invoice manually.

If PayPal does not fully support PayPal Vaulting for your country or region but does support PayPal Advanced Cards, you may still be able to use this module for one-time payments. In this scenario, your customers will not have the option to save payment methods.

Merchant Country Requirements

PayPal only supports PayPal Vault for merchants in specific countries.

PayPal currently enables vaulting for merchants in the United States, Canada, the United Kingdom, Australia, and the following EU countries:

Belgium, Bulgaria, The Republic of Cyprus, Czech Republic, Germany, Denmark, Estonia, Spain, Finland, France, Greece, Hungary, Italy, Lithuania, Luxembourg, Latvia, Malta, Netherland, Poland, Portugal, Romania, Sweden, Slovenia, and Slovakia.

Unlinking your account prevents WHMCS from interacting with PayPal.

Click Unlink PayPal Account to irreversibly remove the link to your PayPal account for both modules.

Refresh PayPal Account

If a PayPal feature is unavailable or an error occurs, a Refresh PayPal Account option will display, allowing you to check your PayPal account’s status. You may wish to do this if, for example, you or PayPal have made changes to your merchant account.

The system will check:

  • Whether you are able to receive payments to your linked PayPal accounts.
  • Your access to PayPal features like PayPal Vault.
  • A checkmark in the displayed results indicates that you are in good standing and able to receive payments (Payments Receivable), your email is verified (Email Verified), or you can use a specific PayPal feature.

Disputes

You can manage disputes for this module from within WHMCS at Billing > Disputes.

Payment Gateway Balances

You can view your PayPal merchant account balance directly within the WHMCS Admin Area at Billing > Transactions List. You can view balances in the transaction list and in the transaction details for individual transactions.

For more information, see Viewing Balances and Transactions.

Troubleshooting

  • If your WHMCS installation’s URL has changed because you moved it, you must update the webhook URL in PayPal. For more information, see Update the PayPal Webhook URL.
  • A Transaction ID already exists message for PayPal Payments transactions at Billing > Gateway Log may not indicate a problem. For more information, see PayPal Transaction ID Errors.

You can find information about most payment gateway-related errors in the logs at Billing > Gateway Log and in the Module Log.

Last modified: June 5, 2024