PayPal Payments

About this Module

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 with some payment methods.

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 PayPal-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 using PayPal Advanced Checkout.

Supported Features

Type	One Time	Recurring	Refunds	3D Secure
Token	Yes	Yes	Yes	Yes

Remote Update Card	Remote Delete Card	AddPayMethod API
No	Yes	No

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. If it does not, this module will not function correctly.
2. Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
3. Choose the Payments category.
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 configure a PayPal Sandbox account for testing purposes, see Test Mode below.
6. Log in to your chosen PayPal account or sign up for a new one. API credentials will populate, WHMCS will save them automatically, and the page will refresh.
7. 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.
8. Optionally, enter a new display name for Display Name.
   • By default, this module uses PayPal as the Client Area display name.
   • You will see the name that you enter here when you configure the payment gateway at Configuration () > System Settings > Payment Gateways.
9. Uncheck Test Mode.
   We enable Test Mode by default for this payment gateway.
10. Click Save Changes.

For a step-by-step walkthrough of the setup process, see Start Using 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. Check Test Mode.
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 visually separate from the PayPal checkout experience.

• This module uses the PayPal account settings that you configure for the PayPal Payments module.
• You cannot display the unbranded credit and debit card options that PayPal Card Payments offers on your order form without also displaying the PayPal option from the PayPal Payments module.

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

1. Activate and configure the PayPal Payments module (above).
2. 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.
3. 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.
4. 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 support PayPal Vault for your country or region, you can still use these payment gateways for one-time payments. However, your clients will not be able to store their payment method.

Supported Merchant Countries

PayPal currently enables PayPal Vault 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.

Unlink PayPal Account

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
• Whether you have verified your email address.
• 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.

If the system detects problems, it instead displays a warning icon and, if applicable, logs the error to the Activity Log at Configuration () > System Logs.

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. You can view balances in the transaction list and in the transaction details for individual transactions.

Troubleshooting

If your WHMCS installation’s URL has changed because you moved it, you must update the webhook URL in PayPal.

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

Updating the PayPal Webhook URL

If your WHMCS installation's URL has changed because you moved it, you must update the webhook URL in PayPal. This will allow WHMCS to continue to record transactions.

To update the PayPal webhook URL:

1. Log in to the PayPal developer portal.
2. Click Live, which will then display the WHMCS app.
3. Click on the app name.
4. Scroll to the Live Webhooks section and click the edit (pencil) icon.
5. Update Webhook URL to the correct address, ending with /modules/gateways/callback/paypal_ppcpv.php.
6. Click Save.