Integrate Pay Later with the JavaScript SDK v6

Using the JavaScript SDK is one way to support Pay Later offers. For more information about Pay Later offers, including eligibility requirements, see Pay Later (US). Rendering a Pay Later message requires these basic steps. You can configure different options at each step, as needed.

Load the SDK.
Add <paypal-message> components to the page.
Initialize the PayPal Messages instance.

Eligibility

You’re eligible to integrate Pay Later offers in the US if you:

Are a US-based PayPal merchant.
Have a US-facing website.
Transact in US dollars (USD).
Have a one-time payment integration, and Pay Later options are available through PayPal checkout.
Abide by the PayPal Acceptable Use Policy and the Pay Later Messaging Center Program Terms.
Do not edit Pay Later messages with additional content, wording, marketing, or other materials to encourage the use of this product. PayPal reserves the right to take action in accordance with the PayPal User Agreement.
Do not create, display, or host your own Pay Later content. Instead, integrate only the official code as provided by PayPal.

Limitations and terms

The following limitations and terms apply:

Reference Transaction and Recurring Payment integrations aren’t eligible for Pay Later offers.
Website Payments Standard (WPS) integrations aren’t eligible for Pay Later messaging.
Pay in 4 loans to CA residents are made or arranged pursuant to a CA Financing Law License. PayPal, Inc., is a GA Installment Lender Licensee, NMLS #910457. RI Small Loan Lender Licensee.
A Pay Monthly agreement is subject to consumer credit approval. Term lengths and fixed APR of 9.99-35.99% vary based on the customer’s creditworthiness. The lender for Pay Monthly is WebBank. PayPal, Inc. (NMLS #910457): RI Loan Broker Licensee. VT Loan Solicitation Licensee.

Configuration overview

There are 3 primary ways to add and configure messages for your website:

HTML configuration: An HTML configuration uses web component attributes and minimal JavaScript to load and render messages to the page. The only JavaScript that you need for this integration is to initialize the SDK and create a PayPal Messages instance.
JavaScript configuration: A JavaScript configuration uses minimal HTML and relies on JavaScript to configure and load message content. The only HTML that you need for this integration is to add the paypal-messages web component to your page.
Dual (HTML with JavaScript) configuration: You can use a dual configuration (HTML and JavaScript) for advanced message options. This approach fetches and sets content using both HTML attributes and JavaScript options.

The following sections of this page explain more about how to use these approaches, including lists of attributes and other options that you can use. For examples, see Message configuration examples.

Load the messages component

There are two ways to load the messages component of the v6 SDK:

Include an HTML script tag with the v6 SDK core script.
Load the component through JavaScript when you create the v6 SDK instance.

HTML
Dual

<head>
  <!-- Load the v6 SDK core script -->
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  <!-- Load the PayPal Messages script -->
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
</head>

The paypal-message SDK component

The paypal-message SDK component utilizes a custom Lit web component, <paypal-messages>, to render Pay Later messages on a webpage. Web component methods and Web component attributes tell you more about how to use this SDK component.

Web component methods

Accessing the <paypal-messages> web component using JavaScript exposes some methods, which the following table describes.

Method	Description	Arguments	Return value
`setContent`	An exposed method to set the content of the message component	Message content that the `payPalMessages.fetchContent()` method returns	`void`
`getFetchContentOptions`	Extracts and returns the `fetchContent` configuration options from the component’s HTML attributes and properties	None	A content object that it constructs from the HTML attributes for the web component

Web component attributes

The <paypal-messages> web component accepts a variety of attributes to control how a message looks and what it does. Some options are available only through the fetchContent method. For more information about using fetchContent, see Fetch content options.

HTML attribute	Description	Default value
`amount`	Number string with as many as 2 decimal places to represent dollar amounts. Set using JavaScript as a fetch content option. Example inputs: `"50"` → $50.00 <br /> `"50.5"` →$ 50.50	None
`auto-bootstrap`	If `true`, PayPal’s data layer (`PayPalMessages`) automatically picks up this component to fetch content. If `false`, you must use `fetchContent`.	`false`
`currency-code`	A string value of length 3 to represent the currency code of the message. Set using JavaScript as a PayPal messages option and a fetch content option.	None
`logo-position`	A string value that indicates where to place the message branding. Set using JavaScript as a fetch content option. Options: `INLINE` `LEFT` `RIGHT` `TOP`	`LEFT`
`logo-type`	A string value that indicates the desired branding style. Set using JavaScript as a fetch content option. Options: `MONOGRAM` If `logoType` is `MONOGRAM`, `logoPosition` must be `LEFT`. `TEXT` If `logo-type` is `TEXT`, `logo-position` must be `INLINE`. `WORDMARK`	`WORDMARK`
`presentation-mode`	A string value that indicates how to load a message’s Learn More presentation. Set using JavaScript as a Learn More option. Options: `AUTO` `MODAL` `POPUP` `REDIRECT`	`AUTO`
`text-color`	A string value that indicates the message color to use. Set using JavaScript as a fetch content option. Options: `BLACK` `MONOCHROME` `WHITE`	`BLACK`

JavaScript interface

Create a PayPal Messages instance after you create a v6 SDK instance. The following code snippet is the minimum JavaScript requirement for rendering a message.

const messagesInstance = sdkInstance.createPayPalMessages();

The following sections describe the different methods and options that are available:

Instance methods
Instance options
Fetch content options
Learn More options

Instance methods

A PayPal Messages instance has 2 primary, exposed methods. You can use these methods to configure message content and to present Learn More links.

Method	Description	Arguments
`fetchContent`	Fetch message content from the server.	An optional object of Fetch Content Options
`createLearnMore`	Initialize and return a Learn More presentation.	An optional object of Learn More presentation options

Instance options

When you initialize PayPal Messages with createPayPalMessages, you can pass global configuration options. These options apply to content requests for each message that you configure on this page. For example, if the page contains multiple message elements, and each one has a currency-code attribute, then you can configure currencyCode in the createPayPalMessages call, so you don’t have to configure it in each of the elements.

Option	Description	Default value
`currencyCode`	2-digit string that is the currency code for the buyer’s country Set using JavaScript as a fetch content option or using HTML as a web component attribute	None
`shopperSessionId`	A string that represents the shopper’s session ID in this basic format: `6B29FC40-CA47-1067-B21D-00DD010462DA`

Fetch content options

When you use the fetchContent method, you can pass a variety of options to configure the content of a message.

Option	Description	Default value
`amount`	Number string with as many as 2 decimal places to represent dollar amounts Set using HTML as a web component attribute Example inputs: `"50"` → $50.00 <br /> `"50.5"` →$ 50.50 `"50.55"` → $50.55	None
`currencyCode`	3-digit string that is the currency code for message Set using JavaScript as a fetch content option or using HTML as a web component attribute	None
`logoPosition`	A string value that indicates where to place the message branding. Set using HTML as a web component attribute. Options: `INLINE` `LEFT` `RIGHT` `TOP`	`LEFT`
`logoType`	A string value that indicates the desired branding style. Set using HTML as a web component attribute. Options: `MONOGRAM` If `logoType` is `MONOGRAM`, `logoPosition` must be `LEFT`. `TEXT` If `logoType` is `TEXT`, `logoPosition` must be `INLINE`. `WORDMARK`	`WORDMARK`
`onContentReady`	A callback to send when content is received from the server during a call to the fetch content method. This callback takes precedence over `onReady`.	None
`onReady`	A callback to send when content is received from the fetch content method. This could be content from the local cache or from a server. If you omit `onContentReady` or `onTemplateReady`, the system uses this callback.
`onTemplateReady`	A callback to send when content is received from the local cache during a call to the fetch content method. This callback takes precedence over `onReady`.	None
`textColor`	A string value that indicates the message color to use. Set using HTML as a web content attribute. Options: `BLACK` `MONOCHROME` `WHITE`	`BLACK`

Learn More options

Learn More messages typically follow Pay Later messages, and they link to additional information about available Pay Later offers. These messages can appear as modals, popups, or redirects to a new tab. When you call the createLearnMore method, you can use the following options to configure the Learn More presentation.

Option	Description	Default value
`amount`	Number string with as many as 2 decimal places to represent dollar amounts. Set using JavaScript as a fetch content option or using HTML as a web content attribute. Example inputs: `"50"` → $50.00 <br /> `"50.5"` →$ 50.50	None
`presentationMode`	A string value that indicates how to load a message’s Learn More presentation. Set using HTML as a web content attribute. Options: `AUTO` `MODAL` `POPUP` `REDIRECT`	`AUTO`
`onApply`	A callback to send when the user selects the Apply button or link in a Learn More presentation.	None
`onCalculate`	A callback to send when the user the user enters a value in the Amount input field in a Learn More presentation.	None
`onShow`	A callback to send when a Learn More presentation is shown.	None
`onClose`	A callback to send when a Learn More presentation is closed.	None

SDK instance options

PayPal Messages also uses some top-level SDK instance options. The following part of your code provides these options.

const sdkInstance = await window.paypal.createInstance({
  // SDK Instance Options
});

This table describes the options that you can use for configuration at this level.

Option	Description	Default value
`clientToken`	A unique identifier for merchant authentication	None
`pathType`	A string that represents the page on which the message appears. Options: `cart` `checkout` `home` `mini-cart` `product` `product-details` `product-listing` `search-results`	None
`partnerAttributionId`	An identifier for partner integrations	None
`shopperSessionId`	A string that represents the shopper’s session ID in this basic format: `6B29FC40-CA47-1067-B21D-00DD010462DA`	None

Cascading stylesheet (CSS) properties

For styling parts of messages, you can use 2 custom CSS properties.

Option	Description	Default value
`--paypal-message-font-size`	Specify the font size for the message in `px` from `8px` to `16px`. If you specify a value that is outside of this range, the message will use the closest value that is in this range. For example, if you try to use `4px`, the message uses `8px`. If you try to use `24px`, the message uses `16px`.	`14px`
`--paypal-message-text-align`	Alignment of the message: `left` `right` `center`	`left`

Message configuration examples

These examples show how the different configurations work to create a Pay Later message with a Learn More link. Select a tab to view the examples of the 3 basic options:

HTML configuration
JavaScript configuration
Dual (HTML with JavaScript) configuration

HTML
JavaScript
Dual

The HTML configuration uses web component HTML attributes and minimal JavaScript to load and render messages to a page. The only JavaScript that you need for this integration is to initialize the SDK and create a PayPal Messages instance.

To use v6 SDK messages, include 2 scripts on your site: the core SDK package and the PayPal messages SDK package.

<head>
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
</head>

Add the <paypal-message> web component to your page. If you use the auto-bootstrap attribute, PayPal’s data layer (PayPalMessages) automatically picks up this component to fetch content. If you do not use auto-bootstrap, you must use the fetchContent method to fetch and set content.

<paypal-message
  amount="300.00"
  currency-code="USD"
  logo-type="MONOGRAM"
  text-color="MONOCHROME"
></paypal-message>

Create the core SDK instance using your client token, and instantiate PayPal Messages.

// Add the necessary JavaScript to instantiate PayPal Messages:
    const sdkInstance = await window.paypal.createInstance({ clientToken });
    const messagesInstance = sdkInstance.createPayPalMessages();

Add a way to update the PayPal Message amount. This code sample shows how to update the amount attribute on the PayPal Messages web component.

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

When you put it all together, this is the full code sample.

<head>
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
</head>
<body>
  <paypal-message
    amount="300.00"
    currency-code="USD"
    logo-type="MONOGRAM"
    text-color="MONOCHROME"
  ></paypal-message>
  <script>
    const sdkInstance = await window.paypal.createInstance({ clientToken });
    const messagesInstance = sdkInstance.createPayPalMessages();
    function triggerAmountUpdate(amount) {
      const messageElement = document.querySelector('paypal-message');
      messageElement.setAttribute('amount', amount);
    }
  </script>
</body>

Message styling

You can use custom CSS properties and change the logo type and text colors to customize the style of a message.

Note: PayPal Debit Card and PayPal Cashback Mastercard are incompatible with the INLINE logo position. If you use INLINE for the logo position for these payment methods, messages use the default value of LEFT instead.

The following examples show some ways to use these styling options.

Right-aligned, 16px, top logo
Centered, 10px, inline logo

// Add a message to your page using any of the message configuration patterns.
<head>
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
</head>
<body>

// Add CSS
  <style>
    --paypal-message-font-size: 16px;
    --paypal-message-text-align: right;
  </style>

// Add the logo configuration
  <paypal-message
    auto-bootstrap
    amount="300.00"
    currency-code="USD"
    logo-position="TOP"
  ></paypal-message>
  <script>
    const sdkInstance = await window.paypal.createInstance({ clientToken });
    const messagesInstance = sdkInstance.createPayPalMessages();
    function triggerAmountUpdate(amount) {
      const messageElement = document.querySelector('paypal-message');
      messageElement.setAttribute('amount', amount);
    }
  </script>
</body>

Learn More configuration patterns

The message configuration patterns in Message styling use the default Learn More presentation. You can use JavaScript to customize these presentations. The following code example shows how to customize a specific PayPal message’s Learn More presentation that opens when a user selects it. This sample also adds an event listener to the paypal-message-click event.

// Follow the Message JS Config or HTML Config Steps and add a message to your page
<head>
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
</head>
<body>
  <paypal-message></paypal-message>
  <script>
    const sdkInstance = await window.paypal.createInstance({ clientToken });
    const messagesInstance = sdkInstance.createPayPalMessages();
    const content = await messagesInstance.fetchContent({
      amount: "300.00",
      currencyCode: "USD",
      logoType: "MONOGRAM",
      textColor: "MONOCHROME",
      onReady: (content) => messageElement.setContent(content),
    });
    function triggerAmountUpdate(amount) {
      content.update({ amount });
    }

// Create a Learn More Instance. Include an option to change the presentation mode
    const learnMore = await messagesInstance.createLearnMore({
      presentationMode: "POPUP",
    });

// Handle the Message Click Event
// We need to listen to the message clicked event in order to open the learn more modal when clicked. 
    messageElement.addEventListener("paypal-message-click", (event) => {
      event.preventDefault();
      learnMore.open(event.detail.config);
    });
  </script>
</body>

Analytics logging

The following example renders a message using a JavaScript configuration. In this example, there are console.log statements in many of the configuration callback functions and events. The functions in this example log in the console when an event occurs.

Note: For details about how to log when a custom event or hook occurs, see your analytics platform’s documentation. You can put that code in the function body of the event hook properties for the Fetch Content or Learn More configuration objects.

<head>
  <script src="https://www.paypal.com/web-sdk/v6/core"></script>
  <script src="https://www.paypal.com/web-sdk/v6/paypal-messages"></script>
</head>
<body>
  <paypal-message></paypal-message>
  <script>
    const sdkInstance = await window.paypal.createInstance({ clientToken });
    const messagesInstance = sdkInstance.createPayPalMessages();
    const content = await messagesInstance.fetchContent({
      amount: "300.00",
      currencyCode: "USD",
      logoType: "MONOGRAM",
      textColor: "MONOCHROME",
      onTemplateReady: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Cached Template Rendered");
        messageElement.setContent(content);
      },
      onContentReady: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Fetched Content Rendered");
        messageElement.setContent(content);
      },
    });
    function triggerAmountUpdate(amount) {
      content.update({ amount });
    }
    const learnMore = await messagesInstance.createLearnMore({
      onShow: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Learn More Shown");
      },
      onApply: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Learn More Apply");
      },
      onClose: (content) => {
        // ANALYTICS LOG EXAMPLE
        console.log("Learn More Closed");
      },
    });
    messageElement.addEventListener("paypal-message-click", (event) => {
      event.preventDefault();
      learnMore.open(event.detail.config);
      // ANALYTICS LOG EXAMPLE
      console.log("Message Learn More Clicked");
    });
  </script>
</body>

Payment methods

Save payment methods

Features

Integrate Pay Later with the JavaScript SDK v6

Eligibility

Limitations and terms

Configuration overview

Load the messages component

The paypal-message SDK component

Web component methods

Web component attributes

JavaScript interface

Instance methods

Instance options

Fetch content options

Learn More options

SDK instance options

Cascading stylesheet (CSS) properties

Message configuration examples

Message styling

Learn More configuration patterns

Analytics logging

Payment methods

Save payment methods

Features

​Eligibility

​Limitations and terms

​Configuration overview

​Load the messages component

​The paypal-message SDK component

​Web component methods

​Web component attributes

​JavaScript interface

​Instance methods

​Instance options

​Fetch content options

​Learn More options

​SDK instance options

​Cascading stylesheet (CSS) properties

​Message configuration examples

​Message styling

​Learn More configuration patterns

​Analytics logging

Eligibility

Limitations and terms

Configuration overview

Load the messages component

The paypal-message SDK component

Web component methods

Web component attributes

JavaScript interface

Instance methods

Instance options

Fetch content options

Learn More options

SDK instance options

Cascading stylesheet (CSS) properties

Message configuration examples

Message styling

Learn More configuration patterns

Analytics logging