PayPal Checkout

About this Module

- In WHMCS 8.9 and later, we strongly recommend the PayPal Payments payment gateway module for processing payments with PayPal. This module includes all of the latest features for securely processing payments via PayPal, including support for credit and debit cards. - We added this PayPal module in WHMCS 7.9. For information on all of our PayPal integrations, see PayPal.

PayPal Checkout with Smart Payment Buttons gives your buyers a simplified and secure checkout experience. PayPal Checkout 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	One Time	Recurring	Refunds	Reversals
3rd Party	Yes	Yes	Yes	No

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 the appropriate location for your version of WHMCS:
   • For WHMCS 8.0 and later, go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
   • For WHMCS 7.10 and earlier, go to Setup > Products/Services > Payment Gateways and choose All Payment Gateways.
3. Click Activate & Configure for PayPal.
4. When the system prompts you, log in to your existing PayPal account or sign up for a new one.
5. When the system prompts you, 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.

Migrating from PayPal Basic

For help to migrate to the PayPal module from PayPal Basic, see the PayPal Checkout Migration Guide.

Limitations and Restrictions

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.

For more information, see PayPal Checkout SSL Requirement.

The following limitations and restrictions apply to PayPal Checkout:

• Users who choose to use one of the PayPal Checkout express checkout options within the view cart step of the shopping cart workflow will not be asked to select a payment gateway in the checkout step.
• The option to apply credit during checkout for existing customers who have a credit balance is not displayed during express checkout to avoid conflicts with the pre-authorized amount at PayPal.
• MarketConnect Upsells will not be displayed after payment has been pre-authorized with PayPal to avoid changes being made to the cart total after authorization of the payment amount with PayPal.
• Convert to for Processing is not offered in the module configuration. Payments will be made 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 modules configuration does not offer an option to force only one-time payments.

Unlinking Your PayPal Account

Do not use this option if there are PayPal subscriptions you wish to keep.

Clicking Unlink PayPal Account will irreversibly remove the link to your PayPal account. Subscription payments will no longer be recorded in WHMCS.

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 https://developer.paypal.com/developer/applications.
2. Select Live, which will then display the WHMCS app.
3. Click on the app name.
4. Scroll down to the Live Webhooks section and click the edit (pencil) icon.
5. Update the Webhook URL to the correct address, ending with /modules/gateways/callback/paypalwebhooks.php.
6. Click Save.

Checkout

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

Clicking any Checkout with PayPal will launch a modal-based 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 screen with their email address pre-filled.

The View Cart step of the order process will display the PayPal Checkout options in addition to the default Checkout:

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 buttons. 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 routine and select PayPal as the payment method. Upon placing an order, they will be redirected 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 has been cancelled, the cancellation event was received 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 is deposited into your PayPal account, but not recorded in WHMCS, you can troubleshoot this by navigating 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 was made through a different integration app from the one currently linked to your WHMCS installation.

This situation can arise if Unlink PayPal Account on the module configuration was used after the PayPal subscription was originally created. Once the unlink function is used, the subscription payments that pre-date it can no longer be recorded in WHMCS. Such subscriptions will need to be cancelled via the PayPal website. Clients can then create a new subscription under the current integration app linked to your WHMCS installation when their next invoice is due.

An unknown error occurred. Please try again

unknown error occurred will be displayed if data saved by the PayPal payment button is invalid, such as the amount, client's name, email address, postal address, postal code, or country code.

To capture more details, use the Module Debug Log. Examine the logged request and response data. It should become apparent what data is missing or incomplete from the client's profile. 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 case, the Country Code at the end of the request is empty. To correct this, go to Profile for the client and ensure that a country is selected. Then, click Save Changes.

If a Billing Contact is specified, make the change via Contacts instead.

If the currency_code value is not amongst PayPal API's supported currency list then the PayPal Basic module can be used as an alternative in conjunction with the Convert to For Processing setting to transparently convert the payment amounts into a currency which is supported by PayPal.

Server Modules
cPanel/WHM - DirectAdmin - Plesk - Helm 3 - Helm 4 - Ensim - InterWorx - WebsitePanel - Cloudmin
Lxadmin - Virtualmin Pro - XPanel - HyperVM - SolusVM - Cloudmin - WHMSonic - VPS.Net
CentovaCast - SCPanel - MediaCP - GameCP - TCAdmin - Reseller Central - Auto Release - Heart Internet

Registrar Modules
Enom - ResellerClub - Nominet - OpenSRS - ResellOne - OnlineNIC - PlanetDomain - Affordable Domains
TPP Wholesale - TPPInternet - Stargate - Namecheap - NetEarthOne - Bizcn - InternetBS - GMO Internet
12Register - Registercom - DotDNS - WebNIC - Dot.TK - HexoNet - Realtime Register - Registereu
RRPProxy - ResellerCamp - TransIP - Heart Internet - IPMirror - NetRegistry - OVH - VentraIP Wholesale
Email - 101Domain

Fraud Modules
MaxMind - VariLogiX FraudCall - Telesign

Gateway Modules
2CheckOut - AsiaPay - Auth.net Echeck - Authorize.net - Authorize.net CIM - Bank Transfer - BidPay
BluePay - BluePay Echeck - BluePay Remote - Boleto - CashU - CC Avenue - ChronoPay - Direct Debit
EMatters - E-Path - eProcessingNetwork - eWAY Tokens - F2B - Finansbank - GarantiBank - Gate2Shop
Inpay - InternetSecure - IP.Pay - Kuveytturk - Modulo Moip - Mail In Payment - Merchant Partners
Merchant Warrior - IDEALMollie - Moneris - Moneris Vault - Skrill 1-Tap - NaviGate - NETbilling
Netregistry Pay - NoChex - Offline Credit Card - Optimal Payments - PagSeguro - Payflow Pro - Pay Junction
Paymate AU and NZ - Payment Express - PayPal - PayPal Card Payments - PayPal Express Checkout
PayPal Payments - PayPal Payments Pro - PayPoint.net (SecPay) - Payson - Planet Authorize - ProtX VSP Form
PSIGate - Quantum Gateway - Quantum Vault - SagePay - SagePay Tokens v2 - SecurePay
SecurePay AU - Secure Trading - TrustCommerce - USA ePay - WorldPay - WorldPay Invisible