PayPal Payments

About this Module

• We added this payment gateway in WHMCS 8.9.
• WHMCS includes several options for accepting payments through PayPal. For more information, see PayPal.

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 allows merchants to process and store payment methods using PayPal’s latest secure tokenization system, including the advanced security of merchant-level vaulting with PayPal Vault for supported merchants.

When you use PayPal Payments, PayPal Smart Buttons allow clients to make one-click payments, including payment with credit and debit cards, during checkout and on invoices. You can enable the additional PayPal Card Payments module to display a separate unbranded option that accepts credit and debit cards using PayPal Advanced Checkout.

Supported Features

Type	One Time	Recurring	Refunds	Reversals
3rd Party	Yes	Yes	Yes	No

This module supports 3D Secure for newly-entered cards and processing of vaulted (stored) cards.

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. Click Activate & Configure for PayPal Payments.
4. Click Link PayPal Account.
5. Log in to your existing PayPal account or sign up for a new one.
6. Confirm permission for the WHMCS application to access your account.
7. Click Confirm to continue. API credentials will populate and WHMCS will save them automatically.
8. 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.
9. Optionally, enter a new display name for Display Name.
   • By default, this module uses Pay with 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.
10. Click Save Changes.
11. Optionally, configure the PayPal Card Payments module if you want to display a separate, unbranded option to accept credit and debit cards.

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 PayPal 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.

PayPal Card Payments

PayPal Card Payments functions as part of the PayPal Payments module. When you enable this module, it adds a separate option for credit and debit cards that displays without the PayPal Smart Button branding. However, you must still display PayPal Smart Buttons using PayPal Payments alongside this unbranded option.

This module uses the PayPal account settings that you configure for the PayPal Payments module:

• You cannot configure the PayPal Card Payments module if the PayPal Payments module is not active.
• You cannot display these options during checkout without also displaying PayPal Smart Buttons using the PayPal Payments module.
• You cannot deactivate the PayPal Payments module without first deactivating the PayPal Card Payments module.

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 Pay with 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. Click Save Changes.

Features

The payment gateway configuration includes a Features section that lists the available PayPal features and their status for the linked merchant account.

Clicking Refresh Merchant Status refreshes the statuses for the listed features (see below).

Vaulting

In approved 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.  

Other PayPal accounts can use this module to process payments, but PayPal will automatically disable vaulting features:

• Not Available will display for Vault in the Features section of the payment gateway configuration at Configuration () > System Settings > Payment Gateways.
• Merchants who do not have this feature can still use the payment gateway for one-time payments but they and their clients will not see the option to store cards.

If your PayPal account supports vaulting, a Save for Future Use option will display while entering credit card details.

• Checking this option causes the system to attempt to vault the card and add it to the client's list of payment methods.
• If a vaulting attempt fails, the system will not return an error message and will not add the card to the client's payment methods.  

Supported Merchant 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.

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 Merchant Status

Click Refresh Merchant Status to check your PayPal account’s status. The system will check whether you are able to receive payments to your linked PayPal accounts, whether you have verified your email address, and your access to PayPal features. You may wish to do this if, for example, you or PayPal have made changes to your merchant account.

• A checkmark 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.

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.

Common Errors

You may see the following common issues:

Signature Verification Failed

Signature Verification Failed indicates a problem in the payment notification anti-spoof verification. When a payment notification is received from PayPal, WHMCS makes an API request to PayPal confirming that the notification originated from PayPal. Often, this error occurs due to unlinking or relinking PayPal accounts.

An unknown error occurred. Please try again

An unknown error occurred displays when the system attempts to save invalid data for a PayPal payment (for example, the amount, client’s name, email address, postcode, or country code).

To capture more details, use the Module Debug Log to examine the logged request and response data and find the missing or invalid values. For example:

Request

{"intent":"CAPTURE","purchase_units":[{"description":"Bronze Hosting - Invoice #123", "amount":{"currency_code":"USD","value":"25.00"},"invoice_id":123}],"payer":{"name": {"given_name":"WHMCS","surname":"Support"},"email_address":"email@example.com", "address":{"address_line_1":"123 Test Street","postal_code":"ABC 123","country_code":""}}}

Response

{"name":"INVALID_REQUEST","message":"Request is not well-formed, syntactically incorrect, or violates schema.","debug_id":"abc123","details":[{"field":"/payer/address/country_code", "value":"","location":"body","issue":"INVALID_STRING_LENGTH","description":" The value of a field is either too short or too long."},

In this example, the country code at the end of the request is empty. To correct this, go to the client’s profile, select a country, and click Save Changes. If the billing contact was invalid, you would make the change in the Contacts tab.

If the currency_code value is not in the PayPal API’s supported currency list, use the PayPal Basic module with the Convert to For Processing setting to transparently convert the payment amounts into a PayPal-supported currency.