On this page
No Headings
Last updated: June 14, 2026
The PayPal Messages SDK lets you display Pay Later messaging, such as Pay in 4 or Pay Monthly, on your site. With a script tag and a few HTML attributes or JavaScript, you can render customizable financing messages on product pages, cart pages, and at checkout, and update them automatically as cart values change. For more information about Pay Later offers, eligibility, and country availability, see Pay Later overview.
When you finish this guide, your site will include Pay Later messaging.
For a full list of configuration options, see the Pay Later reference.
CLIENT_ID with your sandbox or production client ID.The following steps show how to build a complete Pay Later integration. Steps 2 and 4 include variation-specific examples. For those steps, follow the option that matches your approach.
Add the PayPal JavaScript SDK to the <head> of your website. Include messages in the components parameter.
If you've already added the PayPal JavaScript SDK to your website, add 'messages' to the existing components value, such as components=messages,buttons.
<script
src="https://www.sandbox.paypal.com/sdk/js?client-id=CLIENT_ID&components=messages,buttons"
data-namespace="PayPalSDK">
</script>Add <div> elements where you want Pay Later messaging to appear. The SDK renders a message inside any element that has the data-pp-message attribute.
HTML attributes and the JavaScript configuration object can be used independently or combined. If there are conflicting settings between the two, the inline HTML attribute setting takes precedence. For a complete list of available attributes and their values, see the Pay Later messaging reference.
Configure messages entirely through data-pp-* HTML attributes on the <div> element. The SDK automatically scans for elements with data-pp-message and renders them — no additional JavaScript is required.
The formatting options differ by page type. Replace ENTER_VALUE_HERE with the product price or cart total.
Product page
<div
data-pp-message
data-pp-style-layout="text"
data-pp-style-logo-type="inline"
data-pp-style-text-color="black"
data-pp-style-text-size="12"
data-pp-amount=ENTER_VALUE_HERE
data-pp-placement=product>
</div>Cart
<div
data-pp-message
data-pp-style-layout="text"
data-pp-style-logo-type="inline"
data-pp-style-text-color="black"
data-pp-style-text-size="12"
data-pp-amount=ENTER_VALUE_HERE
data-pp-placement=cart>
</div>Checkout
<div
data-pp-message
data-pp-style-layout="text"
data-pp-style-logo-type="inline"
data-pp-style-text-color="black"
data-pp-style-text-size="12"
data-pp-amount=ENTER_VALUE_HERE
data-pp-placement=payment>
</div>Home page
<div
data-pp-message
data-pp-style-color="white-no-border"
data-pp-style-layout="flex"
data-pp-style-ratio="8x1"
data-pp-amount=ENTER_VALUE_HERE
data-pp-placement=home>
</div>Category page
<div
data-pp-message
data-pp-style-color="white-no-border"
data-pp-style-layout="flex"
data-pp-style-ratio="8x1"
data-pp-amount=ENTER_VALUE_HERE
data-pp-placement=category>
</div>The SDK attaches observers to all data-pp-* attributes on targeted message elements. When you change an attribute — such as updating data-pp-amount from 100 to 200 when a customer updates item quantity in their cart — the SDK automatically detects the change and renders a new message if necessary.
Do not call render() again when updating attributes on existing message elements. However, if new HTML content is dynamically injected into the document and you want to render a message inside the new HTML, call render() again and specify the new targets.
// Update data-pp-amount when cart changes; SDK re-renders automatically
messageElement.setAttribute("data-pp-amount", newPrice);The messages component lets you pass in callback functions that are triggered on certain events. Use these to send data to your own analytics platform.
| Event | Description |
|---|---|
onRender | Invoked after each message renders into the DOM |
onClick | Invoked after a user selects the message |
onApply | Invoked after a user selects the Apply button or link in the pop-up modal |
Add event hooks as properties on the configuration object passed to paypal.Messages():
<head>
<script src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID&components=messages">
</script>
</head>
<body>
<div class="pp-message"></div>
<script>
paypal
.Messages({
amount: 500,
pageType: 'product-details',
style: {
layout: 'text',
logo: {
type: 'primary',
position: 'top'
}
},
onRender: () => {
console.log('Callback called on render')
// Send a render event to your analytics platform
},
onClick: () => {
console.log('Callback called on click')
// Send a click event to your analytics platform
},
onApply: () => {
console.log('Callback called on apply')
// Send an apply event to your analytics platform
}
})
.render('.pp-message');
</script>
</body>You can use the JavaScript configuration to declare shared or common settings, while using HTML attributes to customize individual messages. The SDK renders a message into any element with the data-pp-message attribute or elements matching the target you defined in the Messages() call.
<head>
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=messages"></script>
</head>
<body>
<ul class="listings">
<li class="listing">
<div class="listing__content">
<div class="listing__title">Product Name 1</div>
<div class="listing__price">$50</div>
</div>
<div class="pp-message">
<!-- Pay Later message will be inserted here -->
</div>
</li>
<li class="listing">
<div class="listing__content">
<div class="listing__title">Product Name 2</div>
<div class="listing__price">$100</div>
</div>
<div class="pp-message">
<!-- Pay Later message will be inserted here -->
</div>
</li>
</ul>
<script>
// Grab all product listings on the page
const listings = Array.from(document.querySelectorAll(".listing"));
// Loop through each listing and set data-pp-amount from the product price
listings.forEach((listing) => {
const price = Number(
listing.querySelector(".listing__price").textContent.slice(1)
);
const messageElement = listing.querySelector('.pp-message');
// The SDK monitors message elements for attribute changes
messageElement.setAttribute("data-pp-amount", price);
});
// Render all Pay Later messages with shared style config
paypal
.Messages({
style: {
layout: "text",
logo: {
type: "primary",
position: "top",
},
},
})
.render('.pp-message');
</script>
</body>The JavaScript SDK should only be loaded once. Add the <script> tag in the <head> of your main HTML document. Do not reload the SDK on state changes or router updates.
If the state or routes in your single page app change and render new content and messages, call paypal.Messages.render() again and specify the new targets.
Save your website and publish it to start testing Pay Later messaging. Confirm that messaging displays on all appropriate pages.
When you've finished testing, you're ready to go live:
CLIENT_ID to a production CLIENT_ID in the PayPal JavaScript SDK and in your HTML.Message components, console warnings, and errors include configuration attributes and object validations. Configuration properties have distinct validation checks for input formatting and values. For a full list of accepted options, see the Pay Later messaging reference.
If validation fails, the developer console in your web browser displays warning messages that tell you which property is invalid and what you should do to resolve the issue. Depending on the message type, the library attempts to fall back to the relevant default values.
For a complete list of all configuration options, see the Pay Later reference.