Upgrade your Checkout integration

DocsCurrentStandardADVANCEDBeta

Last updated: Aug 15th, 12:31am

If you have an Express Checkout or PayPal Checkout integration, PayPal recommends upgrading to Expanded Checkout using 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.

Visit the Eligibility page to learn more about the countries, currencies, and card brands that Expanded Checkout supports.

Getting started

Integrate Expanded Checkout to present custom credit and debit card fields to your payers so they can pay with PayPal, debit and credit cards, Pay Later options, Venmo, and alternative payment methods, using your site's branding.

1. Review current integration

Your current integration determines whether you need to gather information to integrate with Expanded Checkout. Select PayPal Checkout or Express Checkout:

PayPal Checkout uses the same APIs as Expanded Checkout. You don’t need to change your API calls or collect parameter information about your current PayPal Checkout integration when you upgrade to Expanded Checkout.

2. Set up your sandbox

Sign up for a developer account

You need a PayPal developer account to get sandbox credentials.

Get your credentials

Follow this onboarding document to get a client ID, client secret, access token, and sandbox account credentials:

Client ID: Authenticates your account with PayPal and identifies an app in your sandbox.

Client secret: Authorizes an app in your sandbox. Keep this secret safe and don't share it.

Access token: Authenticates your app when calling PayPal REST APIs.

Set up your sandbox account

This integration requires a sandbox business account with the Expanded Credit and Debit Card Payments capability. Your sandbox business account should automatically have this capability.

To confirm that Expanded Credit and Debit Card Payments are enabled for you, check your sandbox business account as follows:

Log into the PayPal Developer Dashboard, toggle Sandbox, and go to Apps & Credentials.

In REST API apps, select the name of your app.

Go to Features > Accept payments.

Select the Expanded Credit and Debit Card Payments checkbox and select Save Changes.

Note: If you created a sandbox business account through sandbox.paypal.com, and the Expanded Credit and Debit Card Payments status for the account is disabled, complete the sandbox onboarding steps.

Integrate Expanded Checkout

Before beginning your integration, you need to set up your development environment. See the preceding Getting started section for details.

Set up front end

Set up your front end for Expanded Checkout. Select PayPal Checkout or Express Checkout:

Set up your front end to use PayPal card fields and payment buttons in Expanded Checkout. Include components=buttons,card-fields in your JavaScript SDK <script> tag:

The card-field's component renders the card fields.

The button's component renders the PayPal buttons.

PayPal Checkout JavaScript SDK Script Tag

1<script src="https://www.paypal.com/sdk/js?currency=USD&client-id=YOUR_SANDBOX_CLIENT_ID"></script>

Update SDK Script Tag to Expanded Checkout JavaScript

1<script src="https://www.paypal.com/sdk/js?currency=USD&client-id=YOUR_SANDBOX_CLIENT_ID&components=buttons,card-fields"></script>

Create and render card fields and payment buttons

Set up your front end to use PayPal card fields and start accepting credit and debit card payments. Select PayPal Checkout or Express Checkout:

Update your HTML code by replacing your PayPal Checkout button code with the Expanded Checkout card fields and payment button code sample:

Original PayPal Checkout payment button, HTML

1<div id="paypal-button-container"></div>
2<script>
3  paypal.Buttons({
4    // Button configuration and event handlers
5  }).render('#paypal-button-container');
6</script>

Expanded Checkout card fields and payment button, HTML

1<div id="paypal-button-container"></div>
2<div class="card-fields-container">
3  <div id="card-fields" class="card-fields"></div>
4  <button id="card-fields-submit">Submit</button>
5</div>
6<script>
7  paypal.Buttons({
8    // Button configuration and event handlers
9  }).render('#paypal-button-container');
10  paypal.CardFields({
11    createOrder: function() {
12      return fetch('/create-order', {
13        method: 'post'
14      }).then(function(res) {
15        return res.json();
16      }).then(function(orderData) {
17        return orderData.id; // Use the order ID to create the order
18      });
19    }
20  }).render('#card-fields'); // Render the card fields into #card-fields
21  // Handle the submit button for card fields
22  document.getElementById('card-fields-submit').addEventListener('click', function() {
23    paypal.CardFields().submit().then(function(result) {
24      alert('Payment authorized');
25    }).catch(function(err) {
26      console.error('Payment authorization failed:', err);
27      alert('Payment authorization failed');
28    });
29  });
30</script>

Expanded Checkout card fields and payment buttons example

For a more detailed example, see Integrate PayPal buttons and Card Fields.

Set up server-side processing

You may need to set up server-side processing for your integration. Select PayPal Checkout or Express Checkout:

You don't need to set up server-side processing when you upgrade from PayPal Checkout to Expanded Checkout.

Fine-tune your checkout experience

See Customize your buyers' experience to configure the details of your integration.

Test integration

Before going live, test your integration in the sandbox environment. Learn more about card testing, simulating successful payments using test card numbers and generating card error scenarios using rejection triggers.

Note: Use the credit card generator to generate test credit cards for sandbox testing.

Test the following use cases before going live:

PayPal Payment

Test a purchase as a payer:

Select the PayPal button on your checkout page.

Log in using one of your personal sandbox accounts. This ensures the payments will be sent to the correct account. Make sure that you use the sandbox business account that corresponds to the REST app you are using.

Note the purchase amount in the PayPal checkout window.

Approve the purchase with the Pay Now button. The PayPal window closes and redirects you to your page, indicating that the transaction was completed.

Confirm the money reached the business account:

Log in to the PayPal sandbox using the sandbox business account that received the payment. Remember that the SDK source now uses a sandbox client ID from one of your REST apps, and not the default test ID.

In Recent Activity, confirm that the sandbox business account received the money, subtracting any fees.

Log out of the account.

Card payment

Go to the checkout page for your integration.

Generate a test card using the credit card generator.

Enter the card details in the hosted field, including the name on the card, billing address, and 2-character country code. Then, submit the order.

Confirm that the order was processed.

Log in to your merchant sandbox account and navigate to the activity page to ensure the payment amount shows up in the account.

Go live

Follow this checklist to take your application live:

Log into the PayPal Developer Dashboard with your PayPal business account.

Obtain your live credentials.

Include the new credentials in your integration and Update your PayPal endpoint.

See Move your app to production for more details.