Upgrade your Checkout integration

DocsCurrent

Last updated: Apr 2nd, 11:40pm

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.

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.

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:

Selects a payment button.

Logs into PayPal.

Approves the transaction on PayPal.

Returns to your site where you show the payer a confirmation page.

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

    Copy the sample code and paste it into the code of your checkout page.

    Replace YOUR_CLIENT_ID with your client ID.

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>

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

HTML createOrder example
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>

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

HTML captureOrder example
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>

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.

Go live

Required
Go live

How to take your application live.