Upgrade from JavaScript SDK v4 to latest version

Update your JavaScript integration from checkout.js (v4) to PayPal Web SDK v6 to continue processing PayPal payments, card payments, and related payment methods.

SDK v6 includes the following changes:

• replaces the immediate window.paypal.Buttons() global with an explicit createInstance() architecture.
• adds a required eligibility check before you render any payment component.
• moves order creation and capture out of client-side actions helpers and onto your server.

If your integration uses the payment: and onAuthorize: callbacks from the Payments v1 API, this guide's client-side steps alone don't restore a working integration. Your server also needs to move from the Payments v1 API to the Orders v2 API before you continue.

Check country availability

Make sure this solution is available in your country or territory before upgrading.

1. Find your current checkout.js usage

Search your codebase for the following patterns before you start the migration:

# Script tag inclusion
grep -r "paypalobjects.com/api/checkout" .
grep -r "checkout.js" .
grep -r "paypal-checkout" ./package.json

# API usage patterns
grep -r "paypal.Buttons\b" .
grep -r "paypal.Button\b" .       # older alias
grep -r "paypal.HostedFields" .
grep -r "paypal.Marks" .
grep -r "paypal.Messages" .
grep -r "paypal.BillingAgreement" .
grep -r "payment:" .              # Payments v1 callback
grep -r "onAuthorize:" .          # Payments v1 callback

Determine which steps apply to you

Use your search results to scope your migration. Complete steps 1-5 for all integrations.

For steps 6-10, use the following table to determine which steps apply based on the checkout.js patterns you found.

Then, complete steps 11-12 for all integrations.

2. Review what carries forward from v4

Most v4 script parameters carry forward to v6 with the same value, though several move to a different call.

3. Install the JS SDK v6 package

Remove the checkout.js script tag or the paypal-checkout npm dependency, then install the current package.

# npm
npm install @paypal/paypal-js

# React
npm install @paypal/react-paypal-js

4. Load the SDK and create an instance

In v4, window.paypal was set when the script tag loaded, and a single paypal.Buttons() call configured everything. With v6, you load the script, create an instance with the components you need, and check eligibility before rendering anything.

Before (v4): script load and render

The script tag sets window.paypal as soon as it loads, and this single paypal.Buttons() call both creates the order and renders the button in one step.

paypal.Buttons({
  createOrder: function(data, actions) {
    return actions.order.create({ purchase_units: [{ amount: { value: '10.00' } }] });
  },
  onApprove: function(data, actions) {
    return actions.order.capture();
  }
}).render('#paypal-button-container');

After (v6): create an instance

This loads the SDK with loadCoreSdkScript(), then creates an instance scoped to only the components you declare. No button is rendered yet. That happens in a later step.

import { loadCoreSdkScript } from '@paypal/paypal-js/sdk-v6';

const paypal = await loadCoreSdkScript({ environment: 'sandbox' });

const sdkInstance = await paypal.createInstance({
  clientId: 'YOUR-CLIENT-ID',
  components: ['paypal-payments'],
  pageType: 'checkout',
});

Declare every component you use in the components array. A component you call later but didn't declare here isn't available on the instance at runtime.

Confirm sdkInstance resolves before you continue.

5. Check payment method eligibility

In v4, the SDK determined which buttons to show, with no way for your code to know why. With v6, the SDK returns eligibility data that you check before rendering any payment component.

const eligibility = await sdkInstance.findEligibleMethods({ currencyCode: 'USD' });

if (eligibility.isEligible('paypal')) {
  // Render the PayPal payment component
}

Call findEligibleMethods() after createInstance() and before you render any component. If you render a component for a payment method that isn't eligible, it throws an error. Add loading state around this call so the page doesn't flash unrendered content while it resolves.

Confirm eligibility.isEligible('paypal') returns a boolean.

6. Replace your button flow

The v6 SDK replaces the paypal.Buttons() object with a payment session. The actions object doesn't exist in v6, including:

• actions.order.create()
• actions.order.capture()
• actions.redirect()
• actions.restart()
• actions.reject()

Move order creation and capture to your server.

Before (v4): button flow

See the paypal.Buttons() call in step 4. This replaces that same call with a session-based flow.

After (v6): payment session

This creates a payment session whose onApprove and order creation both call your own server endpoints instead of client-side actions. The flow kicks off with session.start() instead of .render().

if (eligibility.isEligible('paypal')) {
  const session = sdkInstance.createPayPalOneTimePaymentSession({
    onApprove: async (data) => {
      await fetch('/api/capture-order', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ orderId: data.orderId }),
      });
    },
    onCancel: () => console.log('Buyer canceled'),
    onError: (err) => console.error('Payment error', err),
  });

  await session.start(
    { presentationMode: 'auto' },
    async () => {
      const res = await fetch('/api/create-order', { method: 'POST' });
      const { orderId } = await res.json();
      return { orderId };
    }
  );
}

Confirm the function you pass to session.start() returns an object with an orderId key, not a plain string. A plain string causes a runtime error.

The following table maps each v4 callback to its v6 equivalent.

After you render the button, confirm:

• the button renders only when isEligible('paypal') returns true.
• selecting the button calls your /api/create-order endpoint.
• a completed payment fires onApprove with the order ID your server returned.

7. Migrate card fields

If your search in step 1 found paypal.HostedFields(), replace it with the card-fields component. This is the largest change in the migration: field initialization, rendering, and submission all changed.

Before (v4): HostedFields

HostedFields.render() configures every card field in one call, targeting each by a CSS selector, and submission is triggered from a click handler.

paypal.HostedFields.render({
  createOrder: function() {
    return fetch('/api/order')
      .then(r => r.json())
      .then(d => d.orderID);
  },
  styles: {
    '.valid': { color: 'green' },
    '.invalid': { color: 'red' }
  },
  fields: {
    number: {
      selector: '#card-number',
      placeholder: 'Card Number'
    },
    cvv: {
      selector: '#card-cvv',
      placeholder: 'CVV'
    },
    expirationDate: {
      selector: '#expiration-date',
      placeholder: 'MM/YYYY'
    },
  }
}).then(function(hostedFields) {
  btn.addEventListener('click', function() {
    hostedFields.submit({
      cardholderName: nameField.value
    });
  });
});

After (v6): card-fields

createCardFields() creates the field controller, then each field is rendered individually with its own .render() call. Submission is now a bare cardFields.submit(), with no cardholder name argument.

const sdkInstance = await paypal.createInstance({
  clientId: 'YOUR-CLIENT-ID',
  components: ['card-fields'],
  pageType: 'checkout',
});

const cardFields = sdkInstance.createCardFields({
  createOrder: async () => {
    const res = await fetch('/api/order', { method: 'POST' });
    const { orderId } = await res.json();
    return { orderId };
  },
  onApprove: async (data) => { /* capture on your server */ },
  onError: (err) => console.error(err),
});

// Render each field individually
cardFields.NumberField().render('#card-number');
cardFields.ExpiryField().render('#expiration-date');
cardFields.CVVField().render('#card-cvv');
cardFields.NameField().render('#card-name');

btn.addEventListener('click', () => {
  cardFields.submit();
});

Confirm every field component renders in its target selector, that selecting your submit button calls cardFields.submit(), and that onApprove fires with the order ID after a successful test card payment.

8. Migrate other components

Map any other v4 component to its v6 equivalent using the following table, then update that component's entry in your components array.

9. Update shipping change callbacks

If your search in step 1 found onShippingChange, split it into two callbacks. The SDK v4 fired one callback, onShippingChange(data, actions), for both address changes and shipping option selection.

Before (v4): onShippingChange

A single onShippingChange callback branches internally to handle both address changes and shipping option selection, rejecting via actions.reject() on failure.

onShippingChange: function(data, actions) {
  // Handled both address changes and option selection
  return fetch('/api/patch-order', { /* ... */ })
    .then(function(res) {
      if (!res.ok) return actions.reject();
    });
}

After (v6): onShippingAddressChange and onShippingOptionChange

The single callback is split into two dedicated handlers, each patching the order independently. Failures are surfaced by throwing an error instead of calling actions.reject(), which doesn't exist in v6.

onShippingAddressChange: async (data) => {
  const res = await fetch('/api/patch-order', {
    method: 'PATCH',
    body: JSON.stringify({ orderId: data.orderId, address: data.address }),
  });
  if (!res.ok) throw new Error('Address not supported');
},

onShippingOptionChange: async (data) => {
  const res = await fetch('/api/patch-order', {
    method: 'PATCH',
    body: JSON.stringify({ orderId: data.orderId, optionId: data.selectedOption.id }),
  });
  if (!res.ok) throw new Error('Option not available');
}

The actions object doesn't exist in v6 (see step 6). Return an error from your server-side patch endpoint and handle it in onError instead.

Confirm onShippingAddressChange fires when the buyer changes their address, onShippingOptionChange fires when the buyer selects a different shipping option, and an unsupported address or option surfaces through onError.

10. Update your React integration

If you use @paypal/react-paypal-js, move to the v6 components and provider.

Before (v4/v5): PayPalScriptProvider and PayPalButtons

PayPalScriptProvider loads the SDK for the tree beneath it, and PayPalButtons renders the button directly with createOrder and onApprove props.

import {
  PayPalScriptProvider,
  PayPalButtons,
} from "@paypal/react-paypal-js";

function App() {
  return (
    <PayPalScriptProvider options={{ "client-id": "YOUR-CLIENT-ID" }}>
      <PayPalButtons createOrder={createOrder} onApprove={onApprove} />
    </PayPalScriptProvider>
  );
}

After (v6): PayPalProvider and PayPalOneTimePaymentButton

PayPalProvider replaces the script provider and requires you to declare components up front, the same as createInstance() in the vanilla JS flow. PayPalOneTimePaymentButton replaces PayPalButtons, and its createOrder/onApprove callbacks call your server endpoints instead of client-side actions.

import {
  PayPalProvider,
  PayPalOneTimePaymentButton,
} from "@paypal/react-paypal-js/sdk-v6";

function App() {
  return (
    <PayPalProvider
      clientId="YOUR-CLIENT-ID"
      environment="sandbox"
      components={["paypal-payments"]}
      pageType="checkout"
    >
      <CheckoutPage />
    </PayPalProvider>
  );
}

function CheckoutPage() {
  return (
    <PayPalOneTimePaymentButton
      createOrder={async () => {
        const res = await fetch("/api/order", { method: "POST" });
        const { orderId } = await res.json();
        return { orderId };
      }}
      onApprove={async ({ orderId }) => {
        await fetch(`/api/capture/${orderId}`, { method: "POST" });
      }}
      onCancel={() => {}}
      onError={(err) => {}}
    />
  );
}

Two hooks support this pattern. usePayPal() returns loadingStatus, error, and sdkInstance. useEligibleMethods({ payload }) runs an asynchronous eligibility check and returns its own loading state.

11. Test your integration

Load the SDK against the sandbox environment with debug: true for verbose logging, then create an instance scoped to the paypal-payments component:

const paypal = await loadCoreSdkScript({ environment: 'sandbox', debug: true });
const sdkInstance = await paypal.createInstance({
  clientId: 'YOUR-SANDBOX-CLIENT-ID',
  components: ['paypal-payments'],
});

Run through each scenario and confirm the result matches what's expected.

12. Go live

Confirm each of the following before you release the update:

• Your live client ID, retrieved from the Developer Dashboard, replaces the sandbox client ID in createInstance().
• environment: 'sandbox' in loadCoreSdkScript() is changed to environment: 'production'.
• Your server-side Orders v2 calls point to api-m.paypal.com.
• Every debug: true flag is removed.
• The PayPal-Debug-Id header is logged on every Orders v2 API response, for support escalation.
• Your content security policy allows https://www.paypal.com in script-src and frame-src.
• No references to paypalobjects.com/api/checkout.js or the paypal-checkout npm package remain in your production build or cached pages.

Migration checklist

Confirm you've completed every step in this guide, plus the following call sites:

• No remaining calls to the removed actions methods (see step 6).
• Every component you use is declared in createInstance({ components: [...] }) (see step 4).
• findEligibleMethods() runs before any payment component renders (see step 5).
• createOrder returns { orderId } everywhere, not a plain string (see step 6).

Avoid these common migration mistakes

These are the failure modes teams run into most often when a step gets skipped or half-applied.

What's next

• For the full set of components, sessions, and configuration options, review the PayPal Web SDK v6 reference.
• For the server-side order creation, capture, and authorization endpoints this migration depends on, review the Orders v2 API reference.