PayPal Checkout gives your customers a simplified and secure checkout experience. It presents the most relevant payment types with methods like Pay with Venmo, PayPal Credit, credit card payments, iDEAL, Bancontact, Sofort, and other payment types.

Supported Features #

Type: Third-Party

Adding the PayPal Payment Gateway #

To set up the PayPal 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.
4. Log in to your existing PayPal account or sign up for a new one.
5. Confirm permission for the WHMCS application to access your account.
6. Click Confirm to continue. API credentials will populate and WHMCS will save them automatically. The page will refresh.
7. Check Show on Order Form to display this payment method in the Client Area during checkout.
8. Click Save Changes.

Limitations and Restrictions #

The following limitations and restrictions apply to PayPal Checkout:

• Users who choose to use one of the PayPal Checkout express checkout options in the view cart step of the shopping cart workflow will not select a payment gateway in the checkout step.
• The option to apply credit during checkout for existing customers who have a credit balance does not display during express checkout to avoid conflicts with the pre-authorized amount at PayPal.
• MarketConnect promotions will not display after payment is pre-authorized with PayPal to avoid changes being made to the cart total after authorization.
• Convert to for Processing is not available for this module. Payments will process in the client’s selected currency.
• The system will offer clients the subscription option if they are ordering a recurring product on a monthly or annual billing cycle. The module configuration does not offer an option to force only one-time payments.

Unlinking Your PayPal Account #

Clicking Unlink PayPal Account will irreversibly remove the link to your PayPal account. WHMCS will stop recording subscription payments.

Checkout #

With PayPal Checkout, users can choose to check out using PayPal.

Checkout with PayPal #

Clicking Checkout with PayPal will open a payment authorization process. Users will log in to their PayPal accounts and confirm their payment before returning to WHMCS to complete the checkout process.

• When first-time customers return to WHMCS, the registration form will pre-fill the name, email, and billing address.
• Existing users who have not already authenticated will see the login page with their email address pre-filled.

The View Cart step of the order process will display the PayPal Checkout options:

This displays in addition to the default checkout options.

Express Checkout #

Express checkout users will not see a payment method choice after authorizing payment by PayPal. Instead, they will see a message indicating that they have pre-approved payment.

• Carts that only have One-Time, Biennial, or Triennial payment items will immediately include Express Checkout options.
• For carts that contain at least one recurring item (on a Monthly or Annual billing cycle), the client can proceed through the standard WHMCS checkout process and select PayPal as the payment method. After placing an order, the system will redirect them to PayPal to create a subscription.

Disputes #

In WHMCS 8.3 and higher, you can manage disputes for this module from within WHMCS at Billing > Disputes.

Troubleshooting #

Missing and Orphaned Subscriptions #

On WHMCS 8.7.2 or higher, the system may log one of the following entries to the Activity Log at Configuration () > System Logs:

The system has detected a missing subscription. The subscription is not associated with any services, but the event was attributable to a client and/or invoice. #

This message indicates that the subscription is not associated with any service, addon, or domain in the WHMCS database for your installation. However, the system did find an alternate ID to use to identify an associated invoice or client.

If this message begins with [PAYMENT.SALE.COMPLETED], there is not an immediate issue, but you should review the subscription in order to understand why the ID is missing.

• If the subscription is active, update the ID to associate the subscription with the relevant service. If you do not, the message will repeat for each payment.
• If the subscription is cancelled, the cancellation event occurred before the final payment. You do not need to take further action.

The system has detected an orphaned subscription. It is not associated with any services, nor was attributable to an invoice or client. #

This message indicates that the subscription is not associated with any service, addon, or domain in the WHMCS database for your installation. Additionally, the system could not find an alternate ID to use to identify an associated invoice or client.

• If this message begins with [PAYMENT.SALE.COMPLETED] and you updated to WHMCS 8.7.2 more than 48 hours ago, there is a serious problem. The PayPal account received payment, but WHMCS has not recorded it. Investigate the issue immediately to determine the necessary action.
• If this message begins with [BILLING.SUBSCRIPTION.CREATED] and you updated to WHMCS 8.7.2 within the last 48 hours, this is a normal indicator that a user checked out using PayPal just before you upgraded. You do not need to take further action.

Missing Payments in WHMCS #

If a client pays an invoice and a completed payment deposits into your PayPal account, but not recorded in WHMCS, you can troubleshoot this by going to Billing > Gateway Log.

The explanations and resolutions for common problems are listed below:

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.

Seeing this typically indicates that a subscription renewal payment processed through a different integration app from the one that you have currently linked to your WHMCS installation.

This situation can arise if you clicked Unlink PayPal Account in the module configuration after the creation of the PayPal subscription. When you click Unlink PayPal Account, WHMCS cannot record payments for the existing subscriptions. You will need to cancel these subscriptions via the PayPal website. Clients can then create a new subscription under the current integration app on your WHMCS installation when their next invoice is due.

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 amoount, 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 protected]",
"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, anc 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.

Last modified: October 31, 2024