Upgrade

SDK

Last updated: Aug 29th, 1:38pm

PayPal Web SDK Migration Guide: v5 to v6

This guide will help you upgrade your PayPal integration from the v5 JavaScript SDK to the new v6 Web SDK. The v6 SDK introduces a modern, component-based approach, improved security, and a more flexible API.

Key Differences at a Glance

Feature	v5	v6
SDK Script URL	https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID¤cy=USD	https://www.sandbox.paypal.com/web-sdk/v6/core
Global paypal object	All features off this global	createInstance is the only method returned, which then handles SDK set up.
Button rendering	paypal.Buttons({ ... }).render()	"<paypal-button/>" with attached event listener and then calling session.start()
Callbacks	Passed into paypal.Buttons()	Passed into checkout session (ex. createPayPalOneTimePaymentSession)
Venmo support	Shows up automatically in the smart stack	Modular via venmo-payments component

Script Tag & SDK Initialization

v5: You include the SDK with a script tag containing your clientId and configuration in the URL.

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

v6: You load the SDK core script (no clientId in the URL). Initialization is done in JavaScript using a clientToken fetched from your server.

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

Fetching a ClientToken

v5: No clientToken is required in the browser; you use your clientId in the script URL.

v6: You must fetch a browser-safe clientToken from your server before initializing the SDK. This token can be fetched from the client-side or server-side.

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

SDK Instance Creation

v5: No explicit SDK instance; you use global `paypal` object.

v6: You create an SDK instance with the `clientToken` and specify which components you want.

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

Rendering Buttons

v5: You render PayPal buttons directly using paypal.Buttons().render().

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

v6: You use custom elements (<paypal-button> , <venmo-button>) and control their visibility and behavior via JavaScript.

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

Order Creation and Capture

v5: You provide createOrder and onApprove callbacks to the button configuration.

1createOrder: function(data, actions) {
2  // call your server to create an order
3}
4onApprove: function(data, actions) {
5  // call your server to capture the order
6}

v6: You define these as standalone functions and pass them to the payment session.

1async function createOrder() {
2  // call your server to create an order
3}
4async function captureOrder({ orderId }) {
5  // call your server to capture the order
6}

Session and Button Handling

v5: Button logic is handled inside the paypal.Buttons configuration.

v6: You create a payment session and attach a click handler to the button.

1const paypalPaymentSession = sdkInstance.createPayPalOneTimePaymentSession({
2  onApprove, onCancel, onError
3});
4
5paypalButton.addEventListener("click", async () => {
6  await paypalPaymentSession.start(
7    { presentationMode: "auto" },
8    createOrder()
9  );
10});

Eligibility Checks

v5: Eligibily checks are built-in internally prior to every button render.

v6: You can use the findEligibleMethods method or call the find-eligible-methods API on your server.

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

Key Takeaways

v6 is more modular and secure: You must fetch a client token from your server.
UI is now component-based: Use custom elements and sessions for payments.
Eligibility and multiple payment methods are more flexible: Built-in checks and support for Venmo.
Same callbacks, different location: Callbacks are now passed to checkout sessions, not button configs.

For more in depth examples, see the PayPal Web SDK examples repo on Github.