Upgrade to Pay Later v6

Use this guide to upgrade your existing Pay Later messaging integration to the JavaScript SDK v6 to use modular components, a custom <paypal-message> web component, and flexible configuration patterns.

What's changing

This upgrade is recommended. SDK v5 continues to receive security patches but no new features. PayPal has not announced a sunset date.

What's new in v6:

• Modular component loading: Load only the paypal-messages component instead of bundling all SDK features. This can result in smaller payloads and faster page rendering.
• Custom web component: The new <paypal-message> Lit-based element replaces the v5 data-pp-message div pattern, providing improved lifecycle visibility, encapsulation from the containing page, and auto-bootstrap support.
• Flexible authentication: Choose between a client ID passed directly to createInstance() (no server-side setup) or a server-generated client token, depending on your integration needs.
• Built-in caching: Support for local, CDN, and site caching can help deliver faster content visibility and distinguishes between cached and fresh content through separate onTemplateReady and onContentReady callbacks.
• Additional configuration options: Customize logo types, text sizes, logo positions, offer types, presentation modes, and caching types through HTML attributes, JavaScript, or both.

Before you begin

Review these prerequisites and compatibility notes before you start the migration.

Am I affected?

This upgrade applies to you if:

• Your page loads the PayPal SDK using a <script> tag with a client-id query parameter in the URL (for example, sdk/js?client-id=CLIENT_ID&components=messages).
• Your integration uses paypal.Messages() or a div with the data-pp-message attribute to render Pay Later messages.

This upgrade does not apply if:

• You already use https://www.paypal.com/web-sdk/v6/core as your SDK script source.
• You use a third-party platform or plugin that manages the SDK version for you (check with your platform provider).

How to check your current version: Open your browser DevTools, go to the Network tab, and look for the SDK script URL. If it contains sdk/js?client-id=, you are on v5.

Prerequisites

• A PayPal client ID from the PayPal Developer Dashboard. If you already have one from your v5 integration, you can reuse it.
• Access to your website's HTML and JavaScript source files.
• A staging or development environment to test the upgrade before you go live.

Compatibility notes

Unchanged:

• Pay Later eligibility rules and offer types remain the same across SDK versions.
• Sandbox and live environments work with the same client ID you already use.
• All currently supported Pay Later offer types are available in v6.

Deprecated but still works:

• The paypal.Messages() JavaScript interface from v5 is not available in v6. Replace it with createPayPalMessages() and fetchContent(). No grace period has been announced.

Removed:

• The data-pp-message attribute on div elements is removed in v6. Use the <paypal-message> custom element instead.
• The query-parameter-based script URL (sdk/js?client-id=...&components=messages) is replaced by the modular v6 core script (/web-sdk/v6/core).

Upgrade steps

Complete the following steps to update your Pay Later messaging integration from v5 to v6.

Step 1. Replace the SDK script tag and initialize the SDK

The v5 SDK loads through a single script tag with your client ID and component list as URL query parameters. In v6, the SDK uses a separate core script and initializes components through JavaScript.

What changes:

• Script URL changes from sdk/js?client-id=CLIENT_ID&components=messages to /web-sdk/v6/core.
• Component loading moves from URL query parameters to the components array in createInstance().
• Authentication moves from the script URL to the createInstance() configuration object.

<script
  src="https://www.sandbox.paypal.com/sdk/js?client-id=CLIENT_ID&components=messages,buttons"
  data-namespace="PayPalSDK">
</script>

If you use a server-generated client token instead of a client ID, pass clientToken in place of clientId:

const sdkInstance = await window.paypal.createInstance({
  clientToken: "YOUR_SERVER_GENERATED_TOKEN",
  components: ["paypal-messages"],
});

Step 2. Replace the message container element

In v5, you rendered Pay Later messages using a div with the data-pp-message attribute, or by calling paypal.Messages().render() in JavaScript. In v6, you use the <paypal-message> custom HTML element.

What changes:

• The div with data-pp-message attribute is replaced by the <paypal-message> custom element.
• Configuration attributes use new names (for example, logo-type instead of the v5 style object).
• The auto-bootstrap attribute simplifies initialization by handling content fetching automatically.

<div data-pp-message
  data-pp-amount="300.00"
  data-pp-style-logo-type="primary"
  data-pp-style-text-color="black">
</div>

The <paypal-message> element renders as invisible until the SDK fills it with content. If you set auto-bootstrap, PayPal's data layer automatically picks up the component and fetches content without additional JavaScript. If you omit auto-bootstrap, call fetchContent() manually in Step 3.

Step 3. Replace the message rendering logic

In v5, you called paypal.Messages().render() to render the message into a target element. In v6, you create a PayPalMessages instance and either rely on auto-bootstrap or call fetchContent() to retrieve and show message content.

What changes:

• paypal.Messages({...}).render('#container') is replaced by sdkInstance.createPayPalMessages() and fetchContent().
• Rendering callbacks change from v5's render promise to v6's onReady, onTemplateReady, and onContentReady callbacks.
• Dynamic amount updates change from re-rendering to content.update() or setAttribute().

paypal.Messages({
  amount: 300.00,
  placement: 'product',
  style: {
    layout: 'text',
    logo: { type: 'primary', position: 'left' },
    text: { color: 'black', size: 12 }
  }
}).render('#pay-later-message');

<paypal-message
  auto-bootstrap
  amount="300.00"
  logo-type="MONOGRAM"
  text-color="BLACK">
</paypal-message>

// After SDK initialization from Step 1
const messagesInstance = sdkInstance.createPayPalMessages({
  currencyCode: "USD",
});

Step 4. Update dynamic amount handling

If your v5 integration updates the message when the cart total changes, update your amount-change logic to use the v6 pattern.

What changes:

• v5 required re-rendering the entire message component to update the amount.
• v6 uses setAttribute() (HTML configuration) or content.update() (JavaScript configuration) for in-place updates without full re-renders.

// Re-render the entire message with a new amount
paypal.Messages({
  amount: newAmount,
  placement: 'product',
  style: { layout: 'text', logo: { type: 'primary' } }
}).render('#pay-later-message');

function updateMessageAmount(newAmount) {
  const messageElement = document.querySelector('paypal-message');
  messageElement.setAttribute('amount', newAmount);
}

quantityInput.addEventListener('change', (event) => {
  const newAmount = calculateTotal(event.target.value);
  updateMessageAmount(newAmount);
});

Step 5. Update Learn More handling (if applicable)

If your v5 integration includes a Learn More modal, update it to use the v6 createLearnMore() method.

What changes:

• v5 handled Learn More automatically through paypal.Messages(). No separate setup was needed.
• v6 requires explicit createLearnMore() initialization and an event listener on the <paypal-message> element.

// In v5, Learn More was built into paypal.Messages() -- no separate code needed
paypal.Messages({
  amount: 300.00,
  style: { layout: 'text' }
}).render('#pay-later-message');
// Clicking the message automatically opened the Learn More modal

If you use auto-bootstrap, Learn More opens automatically when a shopper selects the message. You only need explicit createLearnMore() if you want to customize the presentation mode or add callbacks like onShow, onApply, or onClose.

End-to-end example

After you complete all the steps, a fully upgraded integration using the HTML configuration pattern looks like this:

<head>
  <script
    async
    src="https://www.sandbox.paypal.com/web-sdk/v6/core"
    onload="onPayPalWebSdkLoaded()">
  </script>
</head>
<body>
  <paypal-message
    auto-bootstrap
    amount="300.00"
    logo-type="MONOGRAM"
    text-color="MONOCHROME">
  </paypal-message>

  <script>
    async function onPayPalWebSdkLoaded() {
      try {
        const sdkInstance = await window.paypal.createInstance({
          clientId: "YOUR_CLIENT_ID",
          components: ["paypal-messages"],
        });

        const messagesInstance = sdkInstance.createPayPalMessages({
          currencyCode: "USD",
        });

        // Update amount when cart changes
        function triggerAmountUpdate(amount) {
          const messageElement = document.querySelector('paypal-message');
          messageElement.setAttribute('amount', amount);
        }

        // Optional: customize Learn More presentation
        const learnMore = await messagesInstance.createLearnMore({
          presentationMode: "POPUP",
        });

        const messageElement = document.querySelector('paypal-message');
        messageElement.addEventListener('paypal-message-click', (event) => {
          event.preventDefault();
          learnMore.open(event.detail.config);
        });

      } catch (error) {
        console.error(error);
      }
    }
  </script>
</body>

Verify the upgrade

After you complete the steps, run these scenarios in the PayPal sandbox to confirm the upgrade works.

Message renders with correct content

1. Open your page in a browser and navigate to a product or cart page where the Pay Later message should appear.
2. Open DevTools (F12) and check the Network tab for requests to https://www.sandbox.paypal.com/web-sdk/v6/core and https://www.sandbox.paypal.com/web-sdk/v6/paypal-messages.
3. Verify that the <paypal-message> element is visible on the page with a financing message (for example, "Pay in 4 payments of $75.00"). Actual messaging and terms depend on buyer eligibility and approval.
4. Change the cart amount and confirm the message updates to reflect the new installment calculation.

Expected outcome: The Pay Later message shows the correct installment amount. Changing the cart total updates the message without a full page reload. Both SDK network requests return HTTP 200 OK status codes.

SDK version is v6, not v5

1. Open DevTools and go to the Network tab.
2. Search for sdk/js in the network request list.
3. Confirm there are no requests to the v5 URL pattern sdk/js?client-id=.
4. Confirm there is a request to web-sdk/v6/core.
5. In the Console tab, type window.paypal and verify createInstance is a function (this method only exists in v6).

Expected outcome: No v5 SDK script loads. The v6 core script loads successfully. window.paypal.createInstance is defined as a function.

Learn More opens from the message

1. Select the Pay Later message text on the page.
2. Verify that a Learn More overlay (modal, popup, or redirect based on your presentationMode setting) opens with financing details.
3. Close the overlay and confirm the page state is unchanged.

Expected outcome: Selecting the message opens a Learn More presentation showing financing options. The presentation mode matches your configuration (MODAL, POPUP, or REDIRECT). Closing the overlay returns focus to the page without errors in the console.

Troubleshooting and rollback

If you encounter issues after upgrading, use the solutions in this section to diagnose and resolve them, or roll back to v5.

Common issues

const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["paypal-messages"],
});

Rollback

You can typically roll back to v5 while v5 remains supported. If you need to revert:

1. Replace the v6 core script tag with your original v5 script tag:

   <script src="https://www.sandbox.paypal.com/sdk/js?client-id=CLIENT_ID&components=messages"></script>

2. Replace the <paypal-message> element with your original div using the data-pp-message attribute.
3. Replace the v6 JavaScript initialization (createInstance, createPayPalMessages, fetchContent) with your original paypal.Messages().render() calls.
4. Deploy and verify the v5 messages render correctly.

Next steps

• Go-live checklist. Verify your deployment before launch.
• Pay Later integration guide. Full v6 integration reference with all configuration options, styling examples, and analytics setup.

See also

• Pay Later integration guide. Complete v6 integration documentation.
• JavaScript SDK v5 to v6 upgrade guide. Upgrade all SDK components, not only Pay Later messaging.
• PayPal Developer Dashboard. Manage your client ID and credentials.
• PayPal User Agreement. Review the terms that apply to your PayPal account and integrations.
• PayPal Privacy Statement. Learn how PayPal handles personal data.