Upgrade from v5

Use this guide to upgrade your PayPal integration from the JavaScript SDK v5 to the JavaScript SDK v6. The v6 SDK improves security with client tokens, introduces custom elements for UI, and uses payment sessions to manage checkout flows.

---

Compare v5 and v6

The following table shows how the v5 and v6 SDKs are different.

Feature	v5	v6
SDK script URL	You load the SDK with https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD.	You load the SDK with https://www.sandbox.paypal.com/web-sdk/v6/core.
Global paypal object	All features are available from the global object.	You call createInstance, which sets up the SDK.
Button rendering	You render buttons with paypal.Buttons({ ... }).render().	You use <paypal-button/> with an event listener and call session.start().
Callbacks	You pass callbacks into paypal.Buttons().	You pass callbacks into a checkout session, such as createPayPalOneTimePaymentSession.
Venmo support	Venmo is included automatically in the smart stack.	You enable Venmo with the venmo-payments component.

Migration overview

The following sections explain the main changes and concepts you need to consider when upgrading from v5 to v6 of the PayPal JavaScript SDK.

SDK script

In v5, you load the SDK using a script tag with the client ID and configuration directly in the URL.

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

In v6, you load the SDK core script without a client ID in the URL. You initialize with a client token in your JavaScript.

<script async src="https://www.sandbox.paypal.com/web-sdk/v6/core" onload="onPayPalLoaded()"></script>

Fetch a client token

In v5, you do not need a client token in the browser because you use your client ID in the script URL.

In v6, you fetch a browser-safe client token from your server before initializing the SDK. You can fetch this token on the client or the server side.

async function getBrowserSafeClientToken() {
  const response = await fetch("/paypal-api/auth/browser-safe-client-token");
  const { accessToken } = await response.json();
  return accessToken;
}

Set up the SDK instance

In v5, you use the global paypal object.

In v6, you create the SDK instance with the clientToken and specify payment components.

const sdkInstance = await window.paypal.createInstance({
  clientToken,
  components: ["paypal-payments", "venmo-payments"],
  pageType: "checkout",
});

Render payment buttons

In v5, you render PayPal buttons directly through paypal.Buttons().render().

paypal.Buttons({ ... }).render('#paypal-button-container');

In v6, you use custom elements for payment buttons. You control visibility and actions in JavaScript.

<paypal-button id="paypal-button" type="pay" hidden></paypal-button>
<venmo-button id="venmo-button" type="pay" hidden></venmo-button>

Manage orders and callbacks

In v5, you define createOrder and onApprove inside the button configuration.

createOrder: function(data, actions) {
  // call your server to create an order
}
onApprove: function(data, actions) {
  // call your server to capture the order
}

In v6, you define these as standalone functions and pass them to the payment session.

async function createOrder() {
  // call your server to create an order
}
async function captureOrder({ orderId }) {
  // call your server to capture the order
}

Handle sessions and button events

In v5, you handle button logic inside the paypal.Buttons configuration.

In v6, you create a payment session and attach a click handler to the button.

const paypalPaymentSession = sdkInstance.createPayPalOneTimePaymentSession({
  onApprove, onCancel, onError
});

paypalButton.addEventListener("click", async () => {
  await paypalPaymentSession.start(
    { presentationMode: "auto" },
    createOrder()
  );
});

Check eligibility

In v5, eligibility checks are built in internally before rendering each button.

In v6, you check eligibility with the findEligibleMethods method or by calling the server-side API.

const paymentMethods = await sdkInstance.findEligibleMethods({ currencyCode: "USD" });
if (paymentMethods.isEligible("paypal")) {
  setupPayPalButton(sdkInstance);
}

Summary of changes

• v6 is modular and secure. You must fetch a client token from your server before using the SDK.
• You use a component-based UI with custom elements and payment sessions.
• You can take advantage of built-in eligibility checks and support for multiple payment methods, such as Venmo.
• You pass callbacks directly to checkout sessions instead of button configurations.

For detailed code samples and advanced scenarios, see the Javascript SDK v6 examples on GitHub.