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.

If you want to continue offering Pay Later at checkout, integrate Billing With Purchase, instead. It has the same features as Billing Agreement, but works with the payment options you already have.

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

Know before you code

Get sandbox account information

Required
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.

Explore PayPal APIs with Postman

Optional

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

Run in Postman

Go live