Upgrade your checkout integration

If your current integration is Express Checkout - Billing Agreement, you must upgrade to PayPal Checkout. You can use your site’s branding with PayPal Checkout, allowing customers to pay with PayPal, Pay Later options, Venmo, and alternative payment methods.

1. Review your current integration

1. Identify core API calls

Locate the endpoint URLs in your code that manage starting, reviewing, and completing paymetns. Check the API requests for the following METHOD parameter values:

SetExpressCheckout,   GetExpressCheckoutDetails,   CreateBillingAgreement,   DoReferenceTransaction

2. Document parameters

Review the core API calls from your current integration and make a list of the parameters, such as PAYMENTREQUEST_0_AMT.

3. Parameter mapping tool

Map these parameters to the new API using our parameter mapping tool in our PayPal API Transformer.

2. Setup your sandbox

Sign in to your developer account

If you don't already have one, sign up for a PayPal developer account.

Get your sandbox credentials

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

• Client ID: Authenticates your account with PayPal and identifies an app in your sandbox.
• Client secret: Authorizes an app in your sandobx. Keep this secret safe and don't share it.
• Access token: Authenticates your app when calling PayPal REST APIs.

Set up your sandbox account

Follow this account configuration document to set up your sandbox account and test purchases before going live in your live account.

• Log in to the PayPal Developer Dashboard, toggle Sandbox, and go to Apps & Credentials.
• Select Create App.
• Input App Name, and under Type, select Merchant.
• Click Create App.

Set up your front end to use PayPal payment buttons in PayPal Checkout. Select your upgrade path: choose 'For NVP/SOAP API-only integration' if you currently have an API-only integration, or choose 'For NVP/SOAP API and JavaScript SDK v4' if you're currently using checkout.js.

For NVP/SOAP API-only integration

Integrate PayPal's latest JavaScript Web SDK

PayPal's JavaScript Web SDK supports how you want to accept payments on your website. Our SDK handles displaying the buttons for PayPal and other payment methods, so your customers can pay with whatever method they choose. See Getting started for more information.

1. Follow steps in the Integrate PayPal Web SDK guide to set up and customize your PayPal payment buttons with JavaScript Web SDK v6.

For NVP/SOAP API and JavaScript SDK v4

Upgrade your legacy JavaScript from v4 to v6

If you are using a previous version of PayPal's JavascriptSDK (checkout.js), upgrade your SDK to access the full range of features offered by PayPal Checkout.

Step 1: Update the SDK Script

First, you'll need to replace the old checkout.js script tag with the new v6 SDK script.

Note: For production, use the production URL: https://www.paypal.com/web-sdk/v6/core.js

Step 2: Generate a clientToken (server-side)

In v6, you no longer pass your client-id directly in the script tag. Instead, your server must generate a short-lived, browser-safe clientToken.

You will need to create a dedicated endpoint on your server that your frontend can call to fetch this token.

Here’s a conceptual example using Node.js with Express:

1. Create a server endpoint to handle the token request from your frontend.

2. Create a helper function to generate a clientToken. This function will securely call the PayPal API.

For more detailed information, please refer to the official v6 JS Web SDK authentication documentation or see our example repo here.

Step 3: Initialize the SDK and render buttons (client-side)

On your frontend, you’ll fetch the clientToken from your server and use it to initialize the PayPal SDK.

1. Add containers for your payment buttons

2. Fetch the clientToken, create an instance of the PayPal SDK, check for eligible payment methods and handle checkout flow on button click.

By following these steps, you can successfully migrate your legacy integration to the new v6 JS Web SDK and take advantage of its modern features and improvements. For more detailed information, please refer to the official v6 JS Web SDK documentation.

If you have an Express Checkout integration, you must set up server-side processing. You'll need to generate a client token, upgrade your NVP/SOAP API integraiton to the Orders v2 API, and set up a listener to handle API responses.

Core API workflow for billing agreements

For billing agreements without immediate purchase, merchants call SetExpressCheckout with ZERO AMOUNT and billing type parameters, redirect customers to PayPal for authorization, then use CreateBillingAgreement to establish the recurring payment authorization WITHOUT processing an immediate payment.

After customer approval, merchants process recurring payments using DoReferenceTransaction with the stored billing agreement ID. This API accepts variable amounts, making it suitable for usage-based billing, installments, or subscriptions with changing prices. The system requires merchant approval from PayPal for production use and operates under specific transaction limits based on account verification status.

Vault system and tokenization workflow

The modern PayPal Recurring Checkout system revolutionizes recurring payments through a REST-based architecture centered on three core components: the Payment Method Tokens API v3 for secure payment storage, the Orders API v2 for transaction processing, and Smart Payment Buttons for optimized checkout experiences.

The vault architecture securely stores encrypted payment methods using a two-phase token system. Setup tokens (temporary, 3-day expiry) capture initial customer consent and payment method details. These convert to payment method tokens (permanent) that merchants store for recurring transactions. This approach eliminates raw payment data from merchant systems while supporting multiple payment methods per customer, including PayPal wallets, credit cards, and alternative payment options like Venmo.

Processing recurring payments with payment tokens

Once established, payment method tokens enable frictionless recurring transactions through the Orders API. The system supports sophisticated billing scenarios including trial periods, setup fees, and variable amounts. Each transaction includes stored credential indicators for proper authorization routing and supports immediate capture or authorization-capture workflows based on business requirements.

Upgrade your NVP/SOAP API integration to REST APIs

Use the Payment Method Tokens v3 API to create and manage vaulted payment methods, and use the Orders v2 API for processing recurring transactions. The following table shows how a billing agreement setup request in NVP/SOAP API maps to a PayPal Checkout request in the Payment Method Tokens v3 REST API:

To help you construct the request body to support the Orders v2 format, copy and paste your NVP/SOAP reqeuset body into our API Transformer tool.

Changing order details between request and capture

The NVP/SOAP integration uses the CreateBillingAgreement API to establish a billing agreement without an immediate payment. When setting up a billing agreement for future recurring payments without an initial charge, you set the amount to ZERO in SetExpressCheckout, obtain customer approval, then call CreateBillingAgreement to establish the recurring payment authorization.

To create a billing agreement without immediate payment using PayPal Checkout, you need to make calls to the Payment Method Tokens v3 API: a Create setup token POST request to initiate the vault process, and after customer approval, a Create payment token request to finalize the vault storage.

Example payloads

The following are examples of NVP/SOAP API request payloads and how they map to PayPal Checkout requests in the Payment Method Tokens v3 REST API:

Handle responses

Create a handleResponse function to set up a listener that returns an HTTP status code from the API response.

• Set up handleResponse function to make a POST call to the /api/orders endpoint and return an HTTP status code response.
• Declare an errorMessage object to show an error message when handleResponse returns an error code.

For more information about Orders V2 error scenarios, see OrdersV2 Error Messages page.

This example shows a handleResponse() function:

Upgrade IPNs to Webhooks

Replace IPN(Instant Payment Notification) to webhooks for asynchronous event processing.

1. Create Endpoint: Build a secure HTTP POST endpoint (e.g., /webhook) to receive events.
2. Register URL: In your PayPal Developer Dashboard, add your webhook URL and select desired events (e.g., PAYMENT.CAPTURE.COMPLETED).
3. Validate Signatures: Implement signature verification to confirm events come from PayPal.
4. Update Logic: Replace IPN processing with webhook event handling in your code (e.g., update order status on PAYMENT.CAPTURE.COMPLETED).
5. Test Sandbox: Simulate events in the sandbox to ensure your endpoint handles notifications correctly.
6. Go Live: Update your live PayPal settings with your production URL and monitor logs for real-time event processing.

Fine-tune your experience

See the Orders v2 API reference to configure the details of your 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.

PayPal Payment

1. Select the PayPal button on your checkout page.
2. 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
3. Note the purchase amount in the PayPal checkout window.
4. 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:

1. 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.
2. In Recent Activity, confirm that the sandbox business account received the money, subtracting any fees.
3. Log out of the account.

Card payment

1. Go to the checkout page for your integration
2. Generate a test card using the credit card generator.
3. 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.
4. Confirm that the order was processed.
5. Log in to your merchant sandbox account and navigate to the activity page to ensure the payment amount shows up in the account.

Follow this checklist to take your application live:

1. Log into the PayPal Developer Dashboard with your PayPal business account.
2. Obtain your live credentials.
3. Include the new credentials in your integration and Update your PayPal endpoint.

See Move your app to production for more details