Reference

The following tables describe the configuration settings for PayPal pay later messaging.

Script query parameters

Pass these parameters to the PayPal JavaScript SDK script URL as the query parameters that apply to pay later messaging. This is a subset of the possible query parameters that supports the JavaScript SDK.

For the full set of script parameters, see the JavaScript SDK guide.

Sample code

<script
  src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&merchant-id=MERCHANT_ID_IF_NECESSARY&components=messages"
  data-partner-attribution-id="BN_CODE"
  data-namespace="PayPalSDK"
></script>
Parameter Example value Description
client-id a1b2c3d4e5f6 The client ID identifies the PayPal account for the messages component.
merchant-id abcdef123456 The merchant ID of a merchant for whom you're facilitating a message. Use this parameter only for partner, marketplaces, and cart solutions, when you are acting on behalf of another merchant. This parameter is essential to guarantee the merchant sees the best possible message.
data-partner-attribution-id 6f5e4d3c2b1a Also known as BN code. Your BN code is issued to you as part of the onboarding process.
data-namespace PayPalSDK Required if you're using a legacy checkout integration such as checkout.js. The name you'd like to use for the global variable when the SDK loads. For the example value, you would invoke PayPalSDK.Messages() in your integration. Can be any string, except paypal.

Messages function

Create a Message object by invoking paypal.Messages function with the following arguments. Returns a Message object.

Arguments Type Description
Message configuration object Object Configures layout, style, etc. of pay later message

Message object

The Message object contains the following properties:

Property Type Description
render Function Determines where to render the pay later message(s) on the page, and renders them. Accepts a valid CSS selector string, single HTMLElement reference, or array of HTMLElement references. Returns a Promise that resolves after all messages have rendered to the DOM.

Message configuration object

The following table lists all configuration properties that you can set on the configuration object. This configuration object is passed into the Messages function to configure your messages. All of these properties have equivalent HTML custom attributes, which you can add inline on the HTML elements you target for messages. None of these properties are mandatory, although several are recommended. Some properties have default values. If no value or an invalid value is passed, the default value is used.

Note: Properties that are defined using HTML attributes for a given message value overrides duplicate properties set using the configuration object and paypal.Messages function.

Object property (path) HTML attribute Dependency Value Type Possible values Default Description
amount data-pp-amount N/a Number | String Any number, up to two decimals precision N/a The product price or cart amount in dollars. For example, $598.94 should be passed as 598.94. with a weaker value proposition. Strongly recommended so that the best message is rendered
style.layout data-pp-style-layout N/a String text, flex text Sets the overal style/type of message. Can choose between lightweight text-based or flexible, responsive banner
style.logo.type data-pp-style
-logo-type
style.layout === 'text' String primary, alternative, inline, none primary Sets the type of logo used in text layout messages
style.logo.position data-pp-style
-logo-position
style.layout === 'text'
&& (style.logo.type
=== 'primary'
|| style.logo.type
=== 'alternative')
String left, right, top left Sets the position of the logo relative to the message content for messages using a text layout.
style.text.color data-pp-style
-text-color
style.layout === 'text' String black, white, monochrome, grayscale black Sets the color of the text and PayPal/PayPal Credit logos for text layout messages
style.text.size data-pp-style
-text-size
style.layout === 'text' Number 10, 11, 12, 13, 14, 15, 16 12 Sets the font size of the text for text layout messages
style.color data-pp-style-color style.layout === 'flex' String blue, black, white, white-no-border, gray, monochrome, grayscale blue Sets the color of the message background for flex layout messages
style.ratio data-pp-style-ratio style.layout === 'text' String 1x1, 1x4, 8x1, 20x1 1x1 The ratio of the flexible display banner
placement data-pp-placement N/a String home, category, product, cart, payment N/a Informs PayPal's analytics and system logging of the type of e-commerce page on which the message is placed
onApply data-pp-onApply N/a Function Any JavaScript function N/a Callback function called immediately after user selects on an Apply link or button in the pop-up modal
onClick data-pp-onClick N/a Function Any JavaScript function N/a Callback function called immediately after user selects on a message
onRender data-pp-onRender N/a Function Any JavaScript function N/a Callback function called immediately after a message has been successfully rendered into the DOM

style.layout

Object property (path) Inline HTML attribute Possible values
style.layout data-pp-style-layout text, flex

Set this option to one of these values:

Value Description
text Default. Lightweight, contextual message
flex Responsive display banner

style.logo.type

Object property (path) Inline HTML attribute Possible values
style.logo.type data-pp-style-logo-type inline, primary, alternative, none

Set this option to one of these values:

Value Description
primary Default. Single-line PayPal or PayPal Credit logo
alternative "PP" monogram or "PP Credit" logo
inline Recommended. Same as primary logo, but inline with the content
none No logo, text only

style.logo.position

Object property (path) Inline HTML attribute Possible values
style.logo.position data-pp-style-logo-position left, right, top

Set this option to one of these values:

Value Description
left Default. Logo left of the text
right Logo right of the text
top Logo above the text

style.text.color

Object property (path) Inline HTML attribute Possible values
style.text.color data-pp-style-text-color black, white, monochrome, grayscale

Set this option to one of these values:

Value Description
black Default. 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

style.text.size

Object property (path) Inline HTML attribute Possible values
style.text.size data-pp-style-text-size 10, 11, 12, 13, 14, 15, 16

Set this option to one of these values:

Value Description
10 Sets font size to 10px
11 Sets font size to 11px
12 Default. Sets font size to 12px
13 Sets font size to 13px
14 Sets font size to 14px
15 Sets font size to 15px
16 Sets font size to 16px

style.color

Object property (path) Inline HTML attribute Possible values
style.color data-pp-style-color blue, black, white, white-no-border, gray, monochrome, grayscale

Set this option to one of these values:

Value Description
blue Default. 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
grayscale White background with black text and grayscale logo

style.ratio

Object property (path) Inline HTML attribute Possible values
style.ratio data-pp-style-ratio 1x1, 1x4, 8x1, 20x1

Set this option to one of these values:

Value Description
1x1 Default. Ratio of 1x1 that flexes between 120px and 300px wide
1x4 Ratio of 1x4 that is 160px wide
8x1 Ratio of 8x1 that flexes between 250px and 768px wide
20x1 Ratio of 20x1 that flexes between 250px and 1169px wide