Upgrade your Checkout integration

DocsCurrentStandard

Last updated: Apr 25th, 11:11pm

If you have previous checkout integrations, such as Express Checkout or checkout.js, PayPal recommends upgrading your integration with the JavaScript SDK.

The JavaScript SDK has the following benefits:

  • Dynamically renders payment buttons instead of using static images.
  • Launches payment flow in a pop-up window instead of redirecting to a new page.
  • Supports greater control over payment button styles.

Know before you code

Required
Get sandbox account information

Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:

  • Your client ID. Use your client ID when adding payment options to your website.
  • Your personal and business sandbox accounts. Use sandbox accounts to test checkout options.
Dashboard

Optional
Explore PayPal APIs with Postman

You can use Postman to explore and test PayPal APIs. Learn more in our Postman guide.

Payer experience

After the payer authorizes the transaction, the payment buttons call your JavaScript callback rather than redirecting the payer to a return URL.

The payer takes the following actions:

  1. Selects a payment button.
  2. Logs into PayPal.
  3. Approves the transaction on PayPal.
  4. Returns to your site where you show the payer a confirmation page.
Payer experience
1

Add payment buttons

Add the JavaScript SDK and payment buttons to your page.

    1<!DOCTYPE html>
    2<html>
    3
    4<head>
    5 <meta name="viewport" content="width=device-width, initial-scale=1">
    6 <!-- Ensures optimal rendering on mobile devices. -->
    7</head>
    8
    9<body>
    10 <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID">
    11 // Replace YOUR_CLIENT_ID with your sandbox client ID
    12 </script>
    13 <div id="paypal-button-container"></div>
    14</body>
    15
    16</html>

    Modify the code

    1. Copy the sample code and paste it into the code of your checkout page.
    2. Replace YOUR_CLIENT_ID with your client ID.
    2

    Update script

    Update the script tag to pass the parameters you want for your integration, including:

    • The currency of the transaction.
    • The intent of the transaction.
    • Whether the transaction has a Pay Now or a Continue button.
    • Whether the transaction saves payment methods to the vault.

    Example script:

      1<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=EUR&intent=order&commit=false&vault=true">
      2</script>
      3

      Set up transaction

      When your payer selects the PayPal button, the script calls a createOrder() function that you define. In this function, return a promise for a token, payment ID, or order ID from the Orders v2 API.

      Note: The createOrder() function in the JavaScript SDK integration replaces the payment() function in the checkout.js script.

      Migrate the actions.payment.create() call to a server-side integration pattern with the create order endpoint.

      API endpoint: Create order

      1. HTML createOrder example
      2. node.js createOrder example
      1<!DOCTYPE html>
      2<html>
      3
      4<head>
      5 <meta name="viewport" content="width=device-width, initial-scale=1">
      6</head>
      7
      8<body>
      9 <!-- Replace "TEST" with your own sandbox Business account app client ID -->
      10 <script src="https://www.paypal.com/sdk/js?client-id=TEST&currency=USD"></script>
      11 <!-- Set up a container element for the button -->
      12 <div id="paypal-button-container"></div>
      13 <script>
      14 paypal.Buttons({
      15 // Order is created on the server and the order id is returned
      16 createOrder() {
      17 return fetch("/my-server/create-paypal-order", {
      18 method: "POST",
      19 headers: {
      20 "Content-Type": "application/json",
      21 },
      22 // Use the "body" param to optionally pass additional order information
      23 // such as product SKUs and quantities
      24 body: JSON.stringify({
      25 cart: [{
      26 sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
      27 quantity: "YOUR_PRODUCT_QUANTITY",
      28 }, ],
      29 }),
      30 })
      31 .then((response) => response.json())
      32 .then((order) => order.id);
      33 }
      34 }).render('#paypal-button-container');
      35 </script>
      36</body>
      37
      38</html>
      4

      Finalize payment

      After your payer logs in to PayPal and approves the transaction, the script calls the onApprove() function to finalize the transaction.

      Note: For server-side REST integrations, the onAuthorize() function from the checkout.js script is replaced by the onApprove() function in the JavaScript SDK integration.

      Migrate the actions.payment.execute() to a server-side integration with the Orders Capture endpoint. For more information, see Set up standard payments.

      API endpoint: Orders capture

      1. HTML captureOrder example
      2. node.js captureOrder example
      1<!DOCTYPE html>
      2<html>
      3
      4<head>
      5 <meta name="viewport" content="width=device-width, initial-scale=1">
      6</head>
      7
      8<body>
      9 <!-- Replace "TEST" with your own sandbox Business account app client ID -->
      10 <script src="https://www.paypal.com/sdk/js?client-id=TEST&currency=USD"></script>
      11 <!-- Set up a container element for the button -->
      12 <div id="paypal-button-container"></div>
      13 <script>
      14 paypal.Buttons({
      15 // Finalize the transaction on the server after payer approval
      16 onApprove(data) {
      17 return fetch("/my-server/capture-paypal-order", {
      18 method: "POST",
      19 body: JSON.stringify({
      20 orderID: data.orderID
      21 })
      22 })
      23 .then((response) => response.json())
      24 .then((orderData) => {
      25 // Successful capture! For dev/demo purposes:
      26 console.log('Capture result', orderData, JSON.stringify(orderData, null, 2));
      27 const transaction = orderData.purchase_units[0].payments.captures[0];
      28 alert(`Transaction ${transaction.status}: ${transaction.id}\n\nSee console for all available details`);
      29 // When ready to go live, remove the alert and show a success message within this page. For example:
      30 // const element = document.getElementById('paypal-button-container');
      31 // element.innerHTML = '<h3>Thank you for your payment!</h3>';
      32 // Or go to another URL: window.location.href = 'thank_you.html';
      33 });
      34 }
      35 }).render('#paypal-button-container');
      36 </script>
      37</body>
      38
      39</html>
      5

      Fix deprecations

      For checkout.js integrations, upgrade the deprecated integration to the current integration. Check your browser's JavaScript console for errors to debug issues.

      Deprecated integration Upgrade to integration

      Add a script that points to paypalobjects.com/api/checkout.js.

      Add a script that points to paypalobjects.com/sdk/js.

      See Set up standard payments.

      Add a client-side call to paypal.Button.render({}, '#el');.

      Add a client-side call to paypal.Buttons({}).render('#el');.

      See Set up standard payments.

      Add the payment() callback.

      Add the createOrder() callback.

      See Set up standard payments.

      Add the actions.payment.create() call.

      Add a server-side call to /v2/checkout/orders.

      See Set up standard payments.

      Add the onAuthorize() callback.

      Add the onApprove() callback.

      See Set up standard payments.

      Add the actions.payment.execute() call.

      Add a server-side call to /v2/checkout/orders/:id/capture.

      See Set up standard payments.

      Set style.size to small, medium, large, and responsive.

      Set the container element to your preferred size.

      See Customize the payment buttons.

      Pass the client option in the paypal.Button.render() call.

      Pass client-id=xyz to the /sdk/js script tag.

      See Set up standard payments.

      Pass the commit: true or commit: false option in the paypal.Button.render() call.

      Pass commit=true or commit=false to the /sdk/js script tag.

      See Commit.

      Pass the env option in the paypal.Button.render() call.

      Pass client-id=xyz to the /sdk/js script tag and auto-detect the environment.

      See Client ID.

      Pass the locale option in the paypal.Button.render() call.

      Pass locale=xx_XX to the /sdk/js script tag.

      See Locale.

      Pass the style.fundingicons option in the paypal.Button.render() call.

      The card buttons display automatically in the default integration.

      See Set up standard payments.

      Pass the funding.allowed option in the paypal.Button.render() call.

      PayPal automatically decides on the optimal buttons to show to your buyers.

      See Set up standard payments.

      Pass the funding.disallowed option in the paypal.Button.render() call.

      Pass disable-funding or disable-card to the /sdk/js script tag.

      See Disable Funding and Disable card.

      Use paypal.request, paypal.request.get, paypal.request.post.

      Use the built-in browser fetch function, with a polyfill or your AJAX library of choice.

      See Fetch.

      Use paypal.Promise.

      Use the built-in browser Promise, with a polyfill or your promise library of choice.

      See Promise.

      When you set up transaction, pass return and cancel URLs.

      Call actions.redirect() in onAuthorize and onCancel.

      When you set up transaction, do not pass return and cancel URLs.

      Call window.location.href = 'done_page.html' in onApprove.

      Call window.location.href = 'cancel_page.html' in onCancel.

      See Redirect.

      We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies