Pay Later messaging reference

DocsCurrent

Last updated: Mar 14th, 6:13pm

The following reference describes how to customize Pay Later messaging in the code samples.

Script query parameters

Pass these parameters to the JavaScript SDK script URL as the query parameters that apply to Pay Later messaging.

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

Sample code

1<script
2  src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID&merchant-id=MERCHANT_ID&components=messages"
3  data-partner-attribution-id="BN_CODE"
4  data-namespace="PayPalSDK"
5></script>

Parameter

Example value

Description

client-ida1b2c3d4e5f6The client ID identifies the PayPal account for the messages component.
merchant-idabcdef123456The merchant ID of a merchant for whom you're facilitating a message. Only required when you are acting on behalf of another merchant.
data-partner-attribution-id6f5e4d3c2b1aAlso known as BN code. Your BN code is issued to you as part of the onboarding process.
data-namespacePayPalSDKThe name to use as a global variable when the SDK loads. Only required if you're using a legacy checkout integration such as checkout.js. Can be any string, except paypal. For the example value, invoke PayPalSDK.Messages() in your integration.

Messages function

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

Arguments

Type

Description

Message configuration objectObjectConfigures layout, style for Pay Later messaging. Returns a Message object.

Message object

The Message object contains the following properties:

Property

Type

Description

renderFunctionDetermines where to render the Pay Later messages 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 properties have equivalent HTML custom attributes, which you can add inline on the HTML elements you target for messages. For more information about an object property, click the object name in the table.

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)

Possible values

Default

amountAny number, up to two decimal placesNone
currency

  • USD

  • GBP

  • EUR

  • AUD

None
style.layout

  • text

  • flex

text
style.logo.type

  • primary

  • alternative

  • inline

  • none

primary
style.logo.position

  • left

  • right

  • top

left
style.text.color

  • black

  • white

  • monochrome

  • grayscale

black
style.text.size

  • 10

  • 11

  • 12

  • 13

  • 14

  • 15

  • 16

12
style.text.align

  • left

  • center

  • right

left
style.color

  • blue

  • black

  • white

  • white-no-border

  • gray

  • monochrome

  • grayscale

blue
style.ratio

  • 1x1

  • 1x4

  • 8x1

  • 20x1

1x1
pageType

  • home

  • product-listing

  • product-details

  • search-results

  • cart

  • mini-cart

  • checkout

None
contextualComponents

  • PAYPAL_BUTTON

  • PAY_LATER_BUTTON

  • PAYPAL_MARK

  • PAY_LATER_MARK

None
onApplyAny JavaScript functionNone
onClickAny JavaScript functionNone
onRenderAny JavaScript functionNone

amount

The product price or cart amount in dollars. For example, $598.94 should be passed as 598.94. Strongly recommended so that the best message is rendered.

Object Property (path)

Inline HTML Attribute

Value Type

Possible Values

amountdata-pp-amountNumber | StringAny number, up to two decimal places

currency

The buyer's currency code.

Object Property (path)

Inline HTML Attribute

Value Type

currencydata-pp-currencyString

Set this option to one of these values:

Value

Description

USDUnited States of America Dollar
GBPGreat Britain Pound
EUREuro
AUDAustralian Dollar

style.layout

Sets the overal style/type of message. Can choose between lightweight text-based or flexible, responsive banner.

Object Property (path)

Inline HTML Attribute

Value Type

style.layoutdata-pp-style-layoutString

Set this option to one of these values:

Value

Description

textDefault. Lightweight, contextual message.
flexResponsive display banner.

style.logo.type

Sets the type of logo used in text layout messages.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

style.logo.typedata-pp-style-logo-typestyle.layout === 'text'String

Set this option to one of these values:

Value

Description

Preview

primaryDefault. Single-line PayPal or PayPal Credit logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
alternative"PP" monogram or "PP Credit" logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
inlineRecommended. Same as primary logo, but inline with the content,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
noneNo logo, text only,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text

style.logo.position

Sets the position of the logo relative to the message content for messages using a text layout.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

style.logo.positiondata-pp-style-logo-positionstyle.layout === 'text'&& (style.logo.type==='primary'||style.logo.type=== 'alternative')String

Set this option to one of these values:

Value

Description

Preview

leftDefault. Logo left of the text.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
rightLogo right of the text.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
topLogo above of the text.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text

style.text.color

Sets the color of the text and PayPal/PayPal Credit logos for text layout messages.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

style.text.colordata-pp-style-text-colorstyle.layout === 'text'String

Set this option to one of these values:

Value

Description

Preview

blackDefault. Black text with colored logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
whiteWhite text with a white logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
monochromeBlack text with a black logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
grayscaleBlack text with a grayscale logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text

style.text.size

Sets the font size of the text for text layout messages.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

style.text.sizedata-pp-style-text-sizestyle.layout === 'text'Number

Set this option to one of these values:

Value

Description

Preview

10, 11Smaller text sizes.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
12Default. Standard text size.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
13, 14, 15, 16Larger text sizes.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text

style.text.align

Sets the direction the text aligns for text layout messages.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

style.text.aligndata-pp-style-alignstyle.layout === 'text'String

Set this option to one of these values:

Value

Description

Preview

leftDefault. Text is left aligned.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
centerText is center aligned.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
rightText is right aligned.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text

style.color

Sets the color of the message background for flex layout messages.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

style.colordata-pp-style-colorstyle.layout === 'flex'String

Set this option to one of these values:

Value

Description

Preview

blueDefault. Blue background with white text and white logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
blackBlack background with white text and white logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
whiteWhite background with blue text, colored logo, and blue border,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
white-no-borderWhite background with blue text and colored logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
grayLight gray background with blue text and colored logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
monochromeWhite background with black text and black logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
grayscaleWhite background with black text and grayscale logo,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text

style.ratio

The ratio of the flexible display banner.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

style.ratiodata-pp-style-ratiostyle.layout === 'flex'String

Set this option to one of these values:

Value

Description

Preview

1x1Default. Ratio of 1x1 that flexes between 120px and 300px wide,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
1x4Ratio of 1x4 that is 160px wide,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
8x1Ratio of 8x1 that flexes between 250px and 768px wide,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
20x1Ratio of 20x1 that flexes between 250px and 1169px wide,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text

pageType

Informs PayPal's analytics and system logging of the type of e-commerce page on which the message is placed.

Object Property (path)

Inline HTML Attribute

Value Type

pageTypedata-pp-pageTypeString

Set this option to one of these values:

Value

Description

homeThe message is placed on the home page.
product-listingThe message is placed on a product listing page.
product-detailsThe message is placed on the product details page.
search-resultsThe message is placed on a search results page.
cartThe message is placed on the cart page.
mini-cartThe message is placed on the mini-cart page.
checkoutThe message is placed on the checkout page.

contextualComponents

Sets the visual design and content of the message to match an adjacent component. Should be used when the message is placed near checkout buttons or near a PayPal or Pay Later logo or mark.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

contextualComponentsdata-pp-contextualComponentsstyle.layout === 'text' and message is adjacent to button or mark componentString

Set this option to one of these values:

Value

Description

Preview

PAYPAL_BUTTONMessages feature both PayPal and Pay Later. Default uses PayPal monogram logo.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
PAY_LATER_BUTTONMessages only feature Pay Later. Default uses PayPal monogram logo.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
PAYPAL_MARKMessages feature both PayPal and Pay Later. Does not use a PayPal logo.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text
PAY_LATER_MARKMessages only feature Pay Later. Does not use a PayPal logo.,text,message,for,a,Pay,Later,offer,with,12,pixel,font,,left-aligned,,black,text,on,a,white,background,,with,a,PayPal,logo,displaying,the,PayPal,icon,and,name,on,the,left,side,of,the,text

Note: Using one of the above MARK values will make certain other style properties, like those related to the logo, not applicable. 

onApply

Callback function called immediately after user selects on an Apply link or button in the pop-up modal.

Object Property (path)

Inline HTML Attribute

Value Type

Possible Values

onApplydata-pp-onapplyFunctionAny JavaScript function

onClick

Callback function called immediately after user selects on a message.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

onClickdata-pp-onclickFunctionAny JavaScript function

onRender

Callback function called immediately after a message has been successfully rendered into the DOM.

Object Property (path)

Inline HTML Attribute

Dependency

Value Type

onRenderdata-pp-onrenderFunctionAny JavaScript function