Upgrade your JavaScript SDK

UpgradeCurrent

This guide walks you through upgrading an existing v5 JS SDK integration to the v6 Web SDK. v6 introduces a modern, component-based model, requires a browser-safe client token for initialization, and gives you more explicit control over payment sessions and eligibility checks.

Modular & flexible: Choose specific components to load for slimmer payloads.
More secure initialization: v6 uses a server-fetched client token instead of exposing client-id in the script URL.
Cleaner flow control: Callbacks are now passed to payment sessions instead of paypal.Buttons().
Hero Section Image
1

Replace the SDK Script Tag

What changes:

  • v5 used a query-string script (with client-id) to configure and load the SDK.
  • v6 loads a core script (no client-id), then you initialize via JS once your client token is available.
Legacy (v5) Example Code
Deprecated
1
2
3
4
5
6
7
8
9
10
New (v6) Example Code
Upgraded
1
2
3
4
5
6
7
8
9
10

2

Expose a server endpoint to return a browser-safe client token

What changes:

  • v5: No browser token — config lived in the script URL.
  • v6: The browser must fetch a client token from your server before creating the SDK instance.

Your server should:

  1. Authenticate with PayPal using your server credentials.
  2. Request a short-lived client token.
  3. Return it from an endpoint like /paypal-api/auth/browser-safe-client-token.
Client Token Example Code
Upgraded
1
2
3
4
5
6
7
8
9
10

3

Create a v6 SDK instance with the token & the components you need

What changes:

  • v5: You referenced the global paypal and called paypal.Buttons().
  • v6: The global paypal exposes only createInstance(...). You pass the client token and the components you want (e.g., "paypal-payments", "venmo-payments").
Create v6 SDK instance Example Code
Upgraded
1
2
3
4
5
6
7
8
9
10

4

Render buttons using custom elements

What changes:

  • v5: paypal.Buttons({ ... }).render('#container').
  • v6: Use custom elements like and , then attach your own listeners and session logic.
Render Buttons Example Code
Upgraded
1
2
3
4
5
6
7
8
9
10

5

Check eligibility before showing buttons

What changes:

  • v5: Eligibility was implicit before each render.
  • v6: You can explicitly call findEligibleMethods(...) to decide which buttons to show (e.g., PayPal vs. Venmo).
Check Eligibility Example Code
Upgraded
1
2
3
4
5
6
7
8
9
10

6

Move your callbacks into a payment session

What changes:

  • v5: createOrder / onApprove lived inside paypal.Buttons({ ... }).
  • v6: Define them as standalone functions and pass them when you create a session (e.g., createPayPalOneTimePaymentSession).
Callbacks Example Code
Upgraded
1
2
3
4
5
6
7
8
9
10

7

Minimal End-to-End Example (Putting it together)

HTML Example Code
Upgraded
1
2
3
4
5
6
7
8
9
10
JavaScript Example Code
Upgraded
1
2
3
4
5
6
7
8
9
10

8

Test the 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.

9

Go Live

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