On this page
No Headings
Integrate Messaging Configurator
Last updated: June 26, 2026
DOCS
CURRENT
The Pay Later Messaging Configurator is a drop-in JavaScript module that you can add to your admin panel. Merchants can access the admin panel and use the Messaging Configurator to set up, customize, and preview Pay Later messaging. Based on the merchant's configuration, you can display the Pay Later messages to buyers.
Important: Provision the Messaging Configurator only for merchants belonging to PayPal Global Pay Later countries such as:
- Australia (AU)
- France (FR)
- Germany (DE)
- Italy (IT)
- Spain (ES)
- United Kingdom (GB)
- United States (US)
Prerequisites
Ensure that your admin panel meets the following minimum-width requirements of the Messaging Configurator:
- Messaging Configurator: 1200 px
- Messaging Configurator Preview Section: 830 px
Note: The minimum-width requirements for Pay Later messages to be successfully displayed on the website are as follows:
- For text messages: 300 px
- For banner messages: 830 px
1. Load merchant-configurator.js
The JavaScript bundle merchant-configurator.js, required for rendering and using the Messaging Configurator, is hosted in the PayPal Content Delivery Network (CDN). Go to the HTML file that defines the admin-panel page and in the <head> or <body> section, use the following sample code to load merchant-configurator.js.
<script src="https://www.paypalobjects.com/merchant-library/merchant-configurator.js" defer>
</script>2. Render the Messaging Configurator
- Go to the HTML file that corresponds to the admin-panel page where the Messaging Configurator is to be rendered. In the
<body>section use the following code to define a container for the Messaging Configurator:
<div id="messaging-configurator"></div>- In the
<body>section, under a<script>tag, include theMessaging()method as shown in the following syntax and sample to initiate and render the Messaging Configurator.
window.merchantConfigurators?.Messaging({
config: {<Pass saved configuration for return merchants. Pass empty object for merchants using Messaging Configurator for the first time. Pass empty object for merchants whose configuration is not saved>},
locale: '<Enter preferred language to render Messaging Configurator>',
merchantIdentifier: '<Enter merchant's client ID – for first-party partners; merchant's payer ID – for third-party partners>',
partnerClientId: '<Enter partner's client ID>',
partnerName: '<Enter partner's name>',
bnCode: '<Enter build-notation code that identifies a PayPal partner>',
onSave: <Enter callback-function name; callback-function can save the merchant configuration, inject configured messages into selected placements on the merchant website>,
placements: [<Enter the locations you want to offer to merchants for displaying dynamic pay-later messages, as an array of strings>]
});Note: For information on how to retrieve merchant client or payer ID, partner client ID, and BN code, see Credential reference.
Messaging method input parameter
Messaging() accepts an object as the input parameter and renders the Messaging configurator based on the values of the object properties. The object properties are as follows.
| Input parameter | Description |
|---|---|
config (object, optional) | For new merchants or for merchants whose messaging configuration is not saved: When rendering the Messaging Configurator for new merchants, pass an empty object - {} - as the config property's value.For return merchants: After merchants configure their dynamic Pay Later messaging using the admin panel, they publish their configuration. This triggers the onSave event and the configuration being saved is passed to the callback function corresponding to the event. When rendering the Messaging Configurator for return merchants, their saved configuration can be displayed as the default configuration. To do this, pass the saved configuration as the config value when you initiate the Messaging Configurator. The config property's structure depends on the merchant's initial configuration.For information on the config structure, see config object properties. |
locale (string, required) | Preferred language for rendering the Messaging Configurator. |
merchantIdentifier (string, required) | First-party partners: Merchant's client ID. Third-party partners: Merchant's payer ID. For information on how to retrieve the merchant client or payer ID, see Credential reference. |
partnerClientId (string, required) | Partner client ID. For information on how to retrieve the partner client ID, see Credential reference. |
partnerName (string, required) | Partner name. |
bnCode (string, required) | Build-notation code used to uniquely identify the entity placing an API call as a PayPal partner and enable tracking all transactions that originate from the PayPal partner. |
onSave (function, required) | Callback function that is called when the merchant selects Publish in the admin panel triggering the onSave event. The merchant's messaging configuration is passed as an object to the callback function. The function can save the configuration and inject appropriate messages into the merchant's website, based on the specified configuration. |
placements (array of strings, required) | List of locations that the partner displays in the Messaging Configurator. By passing a subset of the possible locations in placements[], partners regulate the locations where merchants display Pay Later messages. Possible values:
Important: All eligible merchants can display Pay Later messages in the product description page, the view cart items page, and the checkout page. So, the minimum configuration for placements[] is placements['checkout', 'product', 'cart']. Partners can additionally allow a merchant to place Pay Later messages in the other possible locations |
The following image shows the Messaging Configurator rendered when a partner passes all possible placement locations to the Messaging() method.
3. [Optional] Customize the Messaging Configurator
You can override the default styling of the Messaging Configurator to adhere to a style compatible with the admin panel. To do this,
- Go the HTML file that corresponds to the admin-panel page where the Messaging Configurator is to be rendered.
- Before the code that renders the Messaging Configurator, include the script to load the CSS with the override class names. Alternatively, before the code that renders the Messaging Configurator, position the following
<style>tag containing the override class names.
<style>.buttonOverride {
margin: 10px;
}
.headerOverride {
color: blue;
}
</style>- Pass the
styleOverridesproperty as part of the input parameter to theMessaging()method.
Messaging({
styleOverrides: {
button: 'buttonOverride',
header: 'headerOverride'
},
bnCode: 'CreditMerchantTesting',
merchantIdentifier: 'SAMPLE_identifier1234',
partnerClientId: 'PARTNER_SAMPLE_iden3456',
partnerName: 'PartnerABC',
onSave: MessagingConfigHandler,
placements: ['homepage', 'cart_preview', 'category', 'checkout', 'product', 'cart', 'product_preview']
});Notes:
- You can override only the Header, Subheader, and Button styling.
- When implementing style overrides, ensure that the Merchant Configurator is similar to the examples in the Validate the integration.
- If you require further customizations, contact PayPal.
4. Define the onSave callback function
After the merchant configures the Pay Later messages in the Messaging Configurator and selects Publish, the onSave event is triggered. The merchant's messaging configuration is passed as a config object to the callback function. You can program the callback function to,
- Save the merchant's configuration.
- Pass the saved object as the
Messaging().configproperty value. This renders the Messaging Configurator with the merchant's saved configuration as the default configuration, when the merchant returns to the admin panel.
In the HTML file that corresponds to the admin-panel page, under the <script> tag where the Messaging() method is included, use the following sample and define the callback function (for example, MessagingConfigHandler) corresponding to the onSave event.
<script>
const MessagingConfigHandler = (data) => {
console.log('Messaging Config', data);
};
Messaging({
bnCode: 'CreditMerchantTesting',
merchantIdentifier: 'SAMPLE_identifier1234',
partnerClientId: 'PARTNER_SAMPLE_iden3456',
partnerName: 'PartnerABC',
onSave: MessagingConfigHandler,
placements: ['homepage', 'cart_preview', 'category', 'checkout', 'product', 'cart', 'product_preview']
});
</script>Callback function input parameter
The callback function accepts the config object as the input parameter (data).
config object properties
The object properties depend on the merchant's configuration. Using the Messaging Configurator, a merchant can configure text and banner messages. The merchant can configure text messages for the following placements:
- product
- cart
- checkout
- product_preview
- cart_preview
The merchant can configure banner messages for the following placements:
- homepage
- category
Example 1: Sample config object when the merchant configures text messages for product, cart, and checkout placements.
{
"product": {
"layout": "text",
"logo-type": "inline",
"placement": "product",
"status": "enabled",
"text-color": "black",
"text-size": "12"
},
"cart": {
"layout": "text",
"logo-type": "inline",
"placement": "cart",
"status": "enabled",
"text-color": "black",
"text-size": "12"
},
"checkout": {
"layout": "text",
"logo-type": "inline",
"placement": "checkout",
"status": "enabled",
"text-color": "black",
"text-size": "12"
},
"product_preview": {
"layout": "text",
"logo-type": "inline",
"placement": "product_preview",
"status": "disabled",
"text-color": "black",
"text-size": "12"
},
"cart_preview": {
"layout": "text",
"logo-type": "inline",
"placement": "cart_preview",
"status": "disabled",
"text-color": "black",
"text-size": "12"
},
"homepage": {
"layout": "flex",
"placement": "homepage",
"status": "disabled",
"color": "black",
"ratio": "8x1"
},
"category_page": {
"layout": "flex",
"placement": "category_page",
"status": "disabled",
"color": "black",
"ratio": "8x1"
}
}Example 2: Sample config object when the merchant configures a text message for product and a banner message for homepage.
{
"product": {
"layout": "text",
"logo-type": "inline",
"placement": "product",
"status": "enabled",
"text-color": "black",
"text-size": "12"
},
"homepage": {
"layout": "flex",
"placement": "homepage",
"status": "enabled",
"color": "black",
"ratio": "8x1"
},
"cart": {
"layout": "text",
"logo-type": "inline",
"placement": "cart",
"status": "disabled",
"text-color": "black",
"text-size": "12"
},
"checkout": {
"layout": "text",
"logo-type": "inline",
"placement": "checkout",
"status": "disabled",
"text-color": "black",
"text-size": "12"
},
"product_preview": {
"layout": "text",
"logo-type": "inline",
"placement": "product_preview",
"status": "disabled",
"text-color": "black",
"text-size": "12"
},
"cart_preview": {
"layout": "text",
"logo-type": "inline",
"placement": "cart_preview",
"status": "disabled",
"text-color": "black",
"text-size": "12"
},
"category_page": {
"layout": "flex",
"placement": "category_page",
"status": "disabled",
"color": "black",
"ratio": "8x1"
}
}| Object.<placement-name>. property | Possible values | Description |
|---|---|---|
status |
| Specifies whether the placement is selected in the Messaging Configurator. |
layout |
| Type of message – light-weight text message or flexible banner message. |
placement |
| Location of the Pay Later message. |
logo-type(present in the object only if layout is text) |
| Specifies how the PayPal logo is rendered in text Pay Later messages. |
text-color(present in the object only if layout is text) |
| Logo and text colour of the Pay Later text messages. |
text-size(present in the object only if layout is text) |
| Font size of the Pay Later text message. |
color(present in the object only if layout is flex) |
| Color of the message background for Pay Later banner messages. |
ratio(present in the object only if layout is flex) |
| Width x height of the flexible banner. |
5. Use merchant-configurator functions to generate inline attributes
To display the Pay Later messages that the merchant customizes, in your front-end code, include the scripts necessary to render the messages. Based on your code structure, you can render the messages using HTML inline attributes or JavaScript.
Use the following merchant-configurator.js functions to auto-generate the HTML inline attributes that you can use in your front-end code:
generateHeaderScript(): Generates the script necessary to load the JS SDK messages component that helps render the Pay Later messages.generateMessagingCodeSnippet(): Uses the parameters of the input object passed to theonSavecallback function and generates the upstream messaging code necessary to render the Pay Later messages, in a specific location, in the format that the merchant chooses.
You can use the getEligibleCountries() function, to retrieve the list of countries where Pay Later offers are supported.
generateHeaderScript()
The function accepts an object as the input parameter and generates the script that must be included in the header part of your front-end code (inside the <head></head> tags), to load the JS SDK messages component. The JS SDK messages component is necessary to render the Pay Later messages.
Note: If you have already implemented the code to include the JS SDK messages component in your front-end code's header, you can skip using the generateHeaderScript() function.
window.merchantConfigurators?.generateHeaderScript({
bnCode: '<Enter build-notation code that identifies a PayPal partner>',
clientId: '<Enter merchant's client ID>',
country: '<Enter merchant's country as a two-letter country code>',
currency: '<Enter merchant's local currency as a three-letter code>'Notes:
- If
generateHeaderScript().countryis US or a country where Global Pay Later offers are not available, the function generates a script as specified in the Output script 1 tab. - If
generateHeaderScript().countryis a country where Global Pay Later offers are available, the function generates a script as specified in the Output script 2 tab. - Ensure to use the appropriate script in your front-end code based on whether the merchant's country is a Global Pay Later eligible country.
The input object properties are as follows.
| Object.property | Type | Description |
|---|---|---|
bnCode | string | Build-notation code used to uniquely identify the entity placing an API call as a PayPal partner and enable tracking all transactions that originate from the PayPal partner. |
clientId | string | First-party partners: Merchant's client ID. Third-party partners: Merchant's payer ID. For information on how to retrieve the merchant client or payer ID, see Credential reference. |
country | string | Two-letter country code corresponding to the merchant's country. Examples: US, AU, FR |
currency | string | Two-letter currency code corresponding to the merchant's local currency. Examples: USD, INR |
generateMessagingCodeSnippet()
The function accepts an object as the input parameter and generates the upstream messaging code necessary to render the Pay Later messages, in a specific location, in the format that the merchant chooses.
Important: Ensure to use the generateMessagingCodeSnippet() function to generate the HTML inline attributes code necessary to display Pay Later messages.
window.merchantConfigurators?.generateMessagingCodeSnippet({
messageConfig: <Individual placement messaging config returned to the onSave callback function> ,
productPrice: <Price of a particular product, to be used in the message to reflect actual installment cost>
});The input object properties are as follows.
| Object.property | Type | Description |
|---|---|---|
messageConfig | object | The config object passed to the onSave callback function contains the entire merchant configuration, for multiple placements. Extract an individual placement's config details and pass them as an object in this property. Example: { "layout": "text", "logo-type": "inline", "placement": "cart", "status": "enabled", "text-color": "black", "text-size": "12" } |
productPrice | string | Product price or cart amount. Example: 500.94 |
getEligibleCountries()
The function returns an array of strings – each string is a two-letter country code corresponding to a country where merchants can offer Pay Later offers.
window.merchantConfigurators.getEligibleCountries()6. Test in sandbox
To enable testing the Messaging Configurator in the PayPal sandbox environment, in the code to render the Messaging Configurator, pass the merchant client ID retrieved from Developer dashboard > Testing Tools > Sandbox Accounts as the merchantIdentifier property value.
For information on how to retrieve the merchant client ID, see Credential reference.
7. Validate the integration
Use the following checklist to validate the Messaging Configurator and the subsequent display of Pay Later messages in the appropriate webpages.
- The Messaging Configurator displayed is similar to the image in Example 1.
- All placements passed to the
Messaging()method are populated as options in the Messaging Configurator. - All message configurations are rendered appropriately in the preview section of the Messaging Configurator.
- For first-time access, the Messaging Configurator is displayed with default values.
- For returning access, when the config object passed to the
onSavecallback is saved and used to populate the Messaging Configurator, the saved configuration overrides the default configuration. - Pay Later messages are rendered appropriately, similar to the images in Example 2, when the necessary HTML inline attributes are defined in your front-end code.
Example 1
Example 2
 |  |  |