checkout

Upgrade your Checkout Integration

If you have a PayPal Checkout integration that uses an earlier version of checkout.js, use this guide to upgrade to the latest PayPal Checkout checkout.js v4 integration. This code keeps you current with the latest button styles and payment features.

Developer video

How to upgrade to PayPal Checkout

Note: If you integrate PayPal Checkout for the first time, follow the steps in the PayPal Checkout Integration Guide.

1. Understand the new PayPal Checkout flow

Before you start the upgrade, understand the key concepts of the PayPal Checkout flow:

  • Rather than use a static image, you must use the checkout.js script to render the PayPal button.
  • The PayPal Checkout flow launches in a pop-up 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.

Buyer's checkout flow

2. Include the JavaScript

Include the Checkout JavaScript on the page:

<script src="https://www.paypalobjects.com/api/checkout.js"></script>

To boost performance, include the script asynchronously on a page so that the script is cached when it is needed:

<script src="https://www.paypalobjects.com/api/checkout.js" async></script>

3. Add the button

Add this HTML to the page where you want to render the PayPal button:

<div id="paypal-button">
<script>
  (function () {
    paypal.Button.render({
      env: 'production', // Or 'sandbox',
      payment: function (data, actions) {
      // You'll configure this in the following steps.
      },
        onAuthorize: function (data, actions) {
          return actions.redirect();
        },
        onCancel: function (data, actions) {
          return actions.redirect();
        },
        onError: function (error) {
          // You will want to handle this differently
          return alert(error);
        }
    }, '#paypal-button');
  })();
</script>

4. Configure payment callback

The payment callback must return the PayPal token from your existing integration.

Form integration

Note: jQuery is required for the form upgrade. If your site does not have jQuery, add <script src="https://code.jquery.com/jquery-3.3.1.slim.min.js"></script>.

If your current integration uses a form similar to this example:

<form id="paypalForm" method="post" action="/classic/setexpresscheckout">
  <input type="hidden" name="action" value="Sale"/>
  <input type="image" src="https://www.paypalobjects.com/webstatic/en_US/i/buttons/checkout-logo-large.png"/>
</form>

To get the form, add this code and set it to a variable. Then, hide the earlier integration:

var paypalForm = document.getElementById('paypalForm');
paypalForm.style.display = 'none';

Then, use this code in your payment callback:

payment: function (data, actions) {
   return new paypal.Promise(function (resolve, reject) {
     $.ajax(paypalForm.getAttribute('action'), {
       crossDomain: true,
       data: $('#paypalForm').serialize(),
       headers: {
         'Accept': 'application/paypal-json-token',
      },
      method: 'POST',
      success: function (response) {
        if (!response || !response.token) {
          throw new Error('There was an error fetching the PayPal token');
          }
          return resolve(response.token);
      },
      error: function (error) {
        return reject(error);
      }
   });
});
}

Note: The Accept header is required and is forwarded with your 302 redirect to PayPal. When the header is present, PayPal responds with a token.

Note: Alternatively, try the redirect upgrade script.

If your current integration uses a GET request with a link tag similar to this example:

<a id="paypalLink" href="/classic/setexpresscheckout">
  <img src="https://www.paypalobjects.com/webstatic/en_US/i/buttons/checkout-logo-large.png"/>
</a>

Add the following code before your render call:

var paypalLink = document.getElementById('paypalLink');
paypalLink.style.display = 'none';

Then, use this code in your payment callback:

payment: function (data, actions) {
   return paypal.request.get(paypalLink.getAttribute('href'), {
     headers: {
       'Accept': 'application/paypal-json-token',
    }
  })
  .then(function (response) {
    if (!response || !response.token) {
      throw new Error('There was an error fetching the PayPal token');
   }
      return response.token;
   })
  .catch(function (err) {
    throw err;
   });
}

Note: The Accept header is required and is forwarded with your 302 redirect to PayPal. When the header is present, PayPal responds with a token.

AJAX integration

If your integration uses a web service and AJAX similar to this example:

<div id="paymentMethods">
    <button id="paypalButton">Pay with PayPal</button>
</div>

<script>
  document.querySelector('#paypalButton').addEventListener('click', function (event) {
    jQuery.post('/create-paypal-token', function (data) {
      window.location = 'https://www.paypal.com/checkoutnow?token=' + data.token;
    });
  });
</script>

Simply place your AJAX call into the payment callback:

payment: function (data, actions) {
  return new paypal.Promise(function (resolve, reject) {
    jQuery.post('/create-paypal-token', function (data) {
      resolve(data.token);
    });
  });
}

5. Test your integration

You are now ready to test your integration.

Feedback