PayPal Checkout Migration Guide

PayPal Checkout is the latest and recommended PayPal integration to use for anybody wanting to accept payments by PayPal.

To learn more about PayPal Checkout and the integration features, please see the PayPal Checkout documentation.

Who this guide applies to

The following guide applies to users of WHMCS who have used the previous PayPal module in WHMCS for automated recurring PayPal subscriptions.

It contains important information about how you can migrate to the newer PayPal Checkout module.

If you are new to WHMCS, or have not used the PayPal Subscription functionality available in prior PayPal integrations, then this guide does not apply to you. You may activate the new "PayPal Checkout" module and/or deactivate the prior "PayPal Basic" module without issue.

Migration Guide

Step 1: Activate the new PayPal Checkout module

Begin by activating the new PayPal Checkout integration.

To do this, navigate to Setup > Payment Gateways and click the Activate & Configure button under the PayPal banner.

A popup will open prompting you to sign in to your PayPal account in order to link it to your WHMCS installation and automatically configure the new module. Complete the process as provided by PayPal to link your PayPal account.

Step 2: Hide the PayPal Basic module

The new PayPal Checkout module is not a direct replacement for the PayPal module that existed before it.

If you have PayPal Subscriptions that were setup either via the previous official PayPal integration from WHMCS (now known as "PayPal Basic"), or via a custom or 3rd party PayPal integration that were later migrated to WHMCS, it is important that you do not deactivate the "PayPal Basic" module. The PayPal Basic module must be kept active in order for recurring payments made via these subscriptions to continue to be recognised and applied automatically.

Uncheck Show on Order Form

1. Navigate to Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payment Gateways.
2. Locate the PayPal Basic module.
3. Uncheck the "Show on Order Form" checkbox.
4. Click Save Changes.

This will stop the PayPal Basic module from showing in the list of available payment methods both during checkout as well as via the Payment Method selection dropdown on invoices (if enabled).

Step 3: Migrating existing products/services

In order to have existing products/services benefit from the new features and functionality of the PayPal Checkout module, it is necessary to change their default payment method to the new module.

This can be done on an individual basis, or can be done in bulk by executing the following queries against your WHMCS database:

UPDATE tblhosting SET paymentmethod='paypalcheckout' WHERE paymentmethod='paypal';
UPDATE tblhostingaddons SET paymentmethod='paypalcheckout' WHERE paymentmethod='paypal';
UPDATE tbldomains SET paymentmethod='paypalcheckout' WHERE paymentmethod='paypal';
UPDATE tblinvoices SET paymentmethod='paypalcheckout' WHERE paymentmethod='paypal' AND status IN ('Draft','Unpaid');

This will update all products, services, addons, domains and draft/unpaid invoices to use the new PayPal Checkout integration to allow users to benefit from the optimised checkout workflow and subscription information procedure.

The PayPal Basic module will remain active to be able to continue to receive and handle IPN notification of payments appropriately.

Step 4: Turn Off IPNs

To prevent payments made via the new integration method being sent via the legacy IPN system, IPNs should be turned off in your PayPal account settings:

1. Navigate to Profile > Profile and Settings > My Selling Tools > Instant Payment Notifications
2. Click the Choose IPN Settings button
3. Select the Disabled option
4. Click Save

Payments and subscriptions made via the PayPal Basic module will continue to be recorded in WHMCS even with IPNs disabled at the account level.