# Integrate Messaging Configurator (/platforms/checkout/pay-later-offers/messaging-config) 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. > **Note:** **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 [#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:** **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 [#1-load-merchant-configuratorjs] 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 `` or `` section, use the following sample code to load **merchant-configurator.js**. ```html lineNumbers ``` ## 2. Render the Messaging Configurator [#2-render-the-messaging-configurator] 1. Go to the HTML file that corresponds to the admin-panel page where the Messaging Configurator is to be rendered. In the `` section use the following code to define a container for the Messaging Configurator: ```html lineNumbers
``` 2. In the `` section, under a ` ``` > **Note:** **Note**: For information on how to retrieve merchant client or payer ID, partner client ID, and BN code, see [Credential reference](/platforms/create-account/#credential-reference). ### Messaging method input parameter [#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](#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](/platforms/create-account/#credential-reference). | | `partnerClientId` (string, required) | Partner client ID.

For information on how to retrieve the partner client ID, see [Credential reference](/platforms/create-account/#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**:
**product****cart****checkout****product\_preview** (optional)**cart\_preview**(optional)**homepage** (optional)**category** (optional)
**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. image ## 3. \[Optional] Customize the Messaging Configurator [#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, 1. Go the HTML file that corresponds to the admin-panel page where the Messaging Configurator is to be rendered. 2. 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 ` ``` 3. Pass the `styleOverrides` property as part of the input parameter to the `Messaging()` method. ```html lineNumbers 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'] }); ``` > **Note:** **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](#validate-the-integration). > * If you require further customizations, contact PayPal. ## 4. Define the onSave callback function [#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, 1. Save the merchant's configuration. 2. Pass the saved object as the [`Messaging().config`](#config) property 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 ` ``` ### Callback function input parameter [#callback-function-input-parameter] The callback function accepts the `config` object as the input parameter (`data`). #### config object properties [#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. ```html lineNumbers { "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. ```html lineNumbers { "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.\.
property** | **Possible values** | **Description** | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `status`
| `enabled``disabled` | Specifies whether the placement is selected in the Messaging Configurator.
| | `layout`
| For product, cart, checkout, product\_preview, cart\_preview placements: `text`For homepage, category placements:`flex` | Type of message – light-weight text message or flexible banner message.
| | `placement`
| `product``cart``checkout``product_preview``cart_preview``homepage``category` | Location of the Pay Later message.
| | `logo-type`
(present in the object only if `layout` is `text`)
| `primary`: PayPal logo is displayed at the start of the Pay Later message, in a single line.`inline`: PayPal logo is displayed in line with the Pay Later messages, in a single line.`alternative`: PP monogram is displayed at the start of the Pay Later message.`none`: Logo is not displayed as part of the Pay Later message. | Specifies how the PayPal logo is rendered in text Pay Later messages.
| | `text-color`
(present in the object only if `layout` is `text`)
| `black`: Black text with colored logo.`white`: White text with a white logo.`monochrome`: Black text with a black logo.`grayscale`: Black text with a grayscale logo. | Logo and text colour of the Pay Later text messages.
| | `text-size`
(present in the object only if `layout` is `text`)
| `10``12``16` | Font size of the Pay Later text message.
| | `color`
(present in the object only if `layout` is `flex`)
| `blue`: Blue background with white text and white logo.`black`: Black background with white text and white logo.`white`: White background with blue text, colored logo, and blue border.`white-no-border`: White background with blue text and colored logo.`gray`: Light gray background with blue text and colored logo.`monochrome`: White background with black text and black logo. | Color of the message background for Pay Later banner messages.
| | `ratio`
(present in the object only if `layout` is `flex`)
| `8 x 1``20 x 1` | Width x height of the flexible banner.
| ## 5. Use merchant-configurator functions to generate inline attributes [#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 the `onSave` callback 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() [#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 `` tags), to load the JS SDK `messages` component. The JS SDK `messages` component is necessary to render the Pay Later messages. > **Note:** **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. #### Syntax ```text lineNumbers window.merchantConfigurators?.generateHeaderScript({ bnCode: '', clientId: '', country: '', currency: '' ``` #### Output script 1 ```text lineNumbers ``` #### Output script 2 ```text lineNumbers ``` > **Note:** **Notes**: > > * If `generateHeaderScript().country` is 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().country` is 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](/platforms/create-account/#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() [#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. > **Note:** **Important**: Ensure to use the `generateMessagingCodeSnippet()` function to generate the [HTML inline attributes code](/pay-later/overview) necessary to display Pay Later messages. #### Syntax ```text lineNumbers window.merchantConfigurators?.generateMessagingCodeSnippet({ messageConfig: , productPrice: }); ``` #### Output - text message ```text lineNumbers
``` #### Output – banner message ```text lineNumbers
``` 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() [#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. #### Syntax ```text lineNumbers window.merchantConfigurators.getEligibleCountries() ``` #### Output ```text lineNumbers ['AU', 'DE', 'ES', 'FR', 'GB', 'IT', 'US'] ``` ## 6. Test in sandbox [#6-test-in-sandbox] To enable testing the Messaging Configurator in the PayPal sandbox environment, in the [code to render the Messaging Configurator](#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](/platforms/create-account/#credential-reference). ## 7. Validate the integration [#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](#generic-configurator-image). * 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 `onSave` callback 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](#cart-image), when the necessary HTML inline attributes are defined in your front-end code. **Example 1** image **Example 2** | | | | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | image | image | image |