Upgrade to checkout.js

This page describes the process that existing PayPal merchants can follow to upgrade to the latest PayPal checkout integration (checkout.js v4).

If you're integrating PayPal for the first time, follow the steps in the PayPal Express Checkout Integration Guide.

These steps are required to complete the upgrade process:

1 Understanding the new PayPal checkout flow.
2 Adding the PayPal button.
3 Setting up the payment.
4 Finalizing the payment.
5 Testing your integration.

1. Understanding the new PayPal checkout flow

Before you start the upgrade, PayPal recommends that you first understand the new PayPal checkout flow.

These are the new key concepts in the checkout flow:

  • Rather than using a static image, you are now required to use the checkout.js script to render the PayPal button.
  • The PayPal checkout flow now launches in a popup window, rather than in a full-page redirect.
  • After the buyer authorizes the transaction, the PayPal checkout flow calls your pre-defined JavaScript callback, rather than redirecting the buyer to a return URL.

2. Adding the PayPal button

In this step, you include the latest version of the checkout.js script on your page to add the PayPal checkout button. You can also choose to customize the button.

<!DOCTYPE html>

<head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://www.paypalobjects.com/api/checkout.js"></script>
</head>

<body>
    <div id="paypal-button"></div>

    <script>
        paypal.Button.render({

            env: 'production', // Or 'sandbox',

            payment: function(data, actions) {
                /* Set up the payment here */
            },

            onAuthorize: function(data, actions) {
                /* Execute the payment here */
            }

        }, '#paypal-button');
    </script>
</body>

3. Setting up the payment

When the buyer clicks on the PayPal button, checkout.js calls the payment() function that you define.

In this function, call your server, and have your server call PayPal to set up the payment, then return the payment ID/token.

PayPal checkout provides the paypal.request.get and paypal.request.post helper functions so you can easily call your server with an AJAX request, and return the payment ID or token as a Promise.

Note: Remember to set up a URL on your server to make a call to PayPal to create the payment, then return the payment ID/token and pass it to checkout.js.

NVP integrations

If you have an existing SetExpressCheckout NVP API call, you'll need to return the token value from the response.

paypal.Button.render({
    payment: function() {
        var SETEC_URL = 'https://mystore.com/api/paypal/set-express-checkout';

        return paypal.request.post(SETEC_URL).then(function(res) {
            return res.token;
        });
    }
}, '#paypal-button-container');

REST integrations

If you have an existing api.paypal.com/v1/payments/payment REST API call, you need to return the id value from the response.

paypal.Button.render({
    payment: function() {
        var CREATE_URL = 'https://mystore.com/api/paypal/create-payment';

        return paypal.request.post(CREATE_URL).then(function(res) {
            return res.id;
        });
    }
}, '#paypal-button-container');

Braintree integrations

If you have an existing Braintree paypalClient.tokenize() call, use the actions.payment.create() instead.

paypal.Button.render({
    braintree: braintree,
    payment: function(data, actions) {
        return actions.payment.create({
            payment: {
                transactions: [
                    {
                        amount: { total: '0.01', currency: 'USD' }
                    }
                ]
            }
        });
    }
}, '#paypal-button-container');

4. Finalizing the payment

After the buyer logs in to PayPal and authorizes the transaction, checkout.js calls the onAuthorize() function that you define.

In this function, call your server, and have your server call PayPal to finalize the transaction.

PayPal checkout provides the paypal.request.get and paypal.request.post helper functions so you can easily call your server with an AJAX request.

Note: Remember to set up a URL on your server to make a call to PayPal to finalize the payment.

NVP integrations

If you have an existing DoExpressCheckoutPayment NVP API call, call your server with the paymentToken and payerID values:

paypal.Button.render({
    payment: function() {
        ...
    },

    onAuthorize: function(data) {
        var DOEC_URL = 'https://mystore.com/api/paypal/do-express-checkout';

        var params = {
            paymentToken: data.paymentToken,
            payerID: data.payerID
        };

        return paypal.request.post(DOEC_URL, params);
    }
}, '#paypal-button-container');

To see a complete working example, please see the demo app.

If you already have return and cancel URLs set up, and you're passing them to PayPal when you set up the payment (in step 3), you can simply opt to redirect the buyer in the onAuthorize and onCancel functions:

onAuthorize: function(data, actions) {
    return actions.redirect();
},

onCancel: function(data, actions) {
    return actions.redirect();
}

REST integrations

If you have an existing api.paypal.com/v1/payments/payment/PAY-XXX/execute REST API call, call your server with the paymentID and payerID values:

paypal.Button.render({
    payment: function() {
        ...
    },

    onAuthorize: function(data) {
        var EXECUTE_URL = 'https://mystore.com/api/paypal/execute-payment';

        var params = {
            paymentID: data.paymentID,
            payerID: data.payerID
        };

        return paypal.request.post(EXECUTE_URL, params);
    }
}, '#paypal-button-container');

To see a complete working example, please see the demo app.

If you already have return and cancel URLs set up, and you're passing them to PayPal when you set up the payment (in step 3), you can simply opt to redirect the buyer in the onAuthorize and onCancel functions:

onAuthorize: function(data, actions) {
    return actions.redirect();
},

onCancel: function(data, actions) {
    return actions.redirect();
}

Braintree integrations

If you have an existing Braintree paypalClient.tokenize() use the onAuthorize() callback instead, and pass data.nonce to your server.

paypal.Button.render({
    payment: function() {
        ...
    },

    onAuthorize: function(data, actions) {
        var BRAINTREE_API = 'https://mystore.com/api/braintree/process-payment';

        return actions.payment.tokenize().then(function() {
            return paypal.request.post(BRAINTREE_API, {
                nonce: data.nonce
            });
        });
    }
}, '#paypal-button-container');

To see a complete working example, please see the demo app.

5. Testing your integration

You're now ready to test your integration.