On this page
No Headings
Pay Later reference
Use this reference to configure advanced options and customize your Pay Later integration.
Last updated: August 11, 2026
The Pay Later Messages SDK helps you display Pay Later messaging, such as Pay in 4 or Pay Monthly, on your site. This reference supplements the integration guide with additional configuration details. Use it as a lookup resource when you need details about a specific attribute, method, or option. For example, use this reference to customize message appearance, configure analytics callbacks, or adjust SDK behavior.
For an explanation of Pay Later offers, eligibility, and country availability, see the Pay Later overview. If you haven't integrated Pay Later messaging yet, start with the integration guide.
For information about handling errors and edge cases during integration, see Error handling in the integration guide.
The <paypal-message> SDK component
The paypal-message SDK component uses a custom Lit web component, <paypal-message>, to render Pay Later messages on a webpage.
The SDK operates in three stages: you initialize an SDK instance with your credentials, create a PayPal Messages instance to activate the messaging module, and then fetch content from PayPal's servers to populate the <paypal-message> element with the appropriate offer for the shopper's location and cart value. The component, instance, and fetch content options that this reference describes each correspond to one of these stages.
Web component attributes
You set these attributes directly on the <paypal-message> HTML tag.
| HTML attribute | Description | Default value |
|---|---|---|
amount | Price string with up to 2 decimal places (for example, "300.00"). Drives the installment calculation. Also settable via fetchContent. | None |
auto-bootstrap | If true, PayPal automatically picks up the component and fetches content without you calling fetchContent manually. If false, you must call fetchContent yourself. | false |
currency-code | 3-character currency code (for example, "USD", "GBP"). Also settable as a PayPal Messages instance option and a fetchContent option. | None |
logo-position | Where to place the PayPal logo relative to the message text. Also settable via fetchContent. Options: INLINE, LEFT, RIGHT, TOP. PayPal Debit Card and PayPal Cashback Mastercard are incompatible with the INLINE logo position. If INLINE is set for these payment methods, the SDK falls back to LEFT. | LEFT |
logo-type | The logo style. Also settable via fetchContent. Options: MONOGRAM (requires logo-position: LEFT), TEXT (requires logo-position: INLINE), WORDMARK. | WORDMARK |
presentation-mode | How the Learn More overlay loads when a shopper clicks the message. Also settable via createLearnMore. Options: AUTO, MODAL, POPUP, REDIRECT. | AUTO |
text-color | Message text color. Also settable via fetchContent. Options: BLACK, MONOCHROME, WHITE. | BLACK |
alternative-prefix | Adds an or prefix to the message. Options: LOWERCASE_OR, UPPERCASE_OR. Setting alternative-prefix forces logo-position to INLINE. | None |
message-length | Requests a shorter message variant. Option: COMPACT. | None |
Web component methods
These methods are available when you have a reference to the <paypal-message> element.
| Method | Description | Arguments | Returns |
|---|---|---|---|
setContent | Manually sets the content of the message component. Used in the JavaScript configuration pattern. | Content returned by fetchContent() | void |
getFetchContentOptions | Reads HTML attributes from the component and returns them as a JavaScript options object. Useful in the hybrid pattern to avoid duplicating configuration. | None | Options object built from the element's HTML attributes |
JavaScript interface
Control PayPal Messages programmatically using these JavaScript methods and configuration options. Use these when building dynamic integrations or when you need fine-grained control over message behavior.
Instance methods
A PayPal Messages instance has two primary methods.
| Method | Description | Arguments |
|---|---|---|
fetchContent | Fetches message content from PayPal's servers. Used when you're not relying on auto-bootstrap. | Optional object of Fetch content options |
createLearnMore | Initializes and returns a Learn More presentation (modal, popup, or redirect). | Optional object of Learn More options |
Instance options
Configure global settings that apply to all PayPal Messages components on your page. Pass these into sdkInstance.createPayPalMessages({...}) to avoid repeating the same configuration on individual message components.
| Option | Description | Default value |
|---|---|---|
currencyCode | 3-character currency code applied to all messages on the page. Also settable per component via the currency-code HTML attribute or as a fetchContent option. | None |
shopperSessionId | Represents the shopper's session. Format: 6B29FC40-CA47-1067-B21D-00DD010462DA. | None |
buyerCountry | The country code for the buyer. This only applies to merchants approved for cross-border presentment. | None |
Fetch content options
Control how individual messages appear and behave when fetching content from PayPal's servers. Pass these into messagesInstance.fetchContent({...}) to customize message appearance, handle callbacks, and set pricing information.
| Option | Description | Default value |
|---|---|---|
amount | Price string with up to 2 decimal places. Also settable via the amount HTML attribute. | None |
currencyCode | 3-character currency code. Also settable via the currency-code HTML attribute. | None |
logoPosition | Logo placement. Options: INLINE, LEFT, RIGHT, TOP. Also settable via the logo-position HTML attribute. PayPal Debit Card and PayPal Cashback Mastercard are incompatible with the INLINE logo position. If INLINE is set for these payment methods, the SDK falls back to LEFT. | LEFT |
logoType | Logo style. Options: MONOGRAM, TEXT, WORDMARK. Also settable via the logo-type HTML attribute. | WORDMARK |
textColor | Message color. Options: BLACK, MONOCHROME, WHITE. Also settable via the text-color HTML attribute. | BLACK |
onContentReady | Callback fired when fresh content arrives from the server. Takes precedence over onReady. | None |
onReady | Callback fired when content is received from either the server or local cache. Used as a fallback if onContentReady and onTemplateReady are not set. | None |
onTemplateReady | Callback fired when content arrives from local cache. Takes precedence over onReady. | None |
alternativePrefix | Adds an or prefix to the message. Options: LOWERCASE_OR, UPPERCASE_OR. Setting alternativePrefix forces logoPosition to INLINE. | None |
messageLength | Requests a shorter message variant. Option: COMPACT. | None |
Learn More options
Customize the Learn More experience that appears when shoppers click on Pay Later messages. Pass these into messagesInstance.createLearnMore({...}) to control presentation mode, track user interactions, and set pricing context.
| Option | Description | Default value |
|---|---|---|
amount | Price string with up to 2 decimal places. | None |
presentationMode | How the Learn More UI appears. Options: AUTO, MODAL, POPUP, REDIRECT. Also settable via the presentation-mode HTML attribute. | AUTO |
onApply | Callback fired when the shopper clicks Apply in the Learn More presentation. | None |
onCalculate | Callback fired when the shopper enters a value in the Amount input in the Learn More presentation. | None |
onShow | Callback fired when the Learn More presentation opens. | None |
onClose | Callback fired when the Learn More presentation closes. | None |
SDK instance options
Authenticate with PayPal and configure your overall SDK integration. Pass these into window.paypal.createInstance({...}) to establish your merchant identity, set page context, and enable PayPal services.
| Option | Description | Default value |
|---|---|---|
clientId | Recommended. Your PayPal client ID. Cannot be used alongside clientToken — choose one. | None |
clientToken | A unique identifier for merchant authentication. Requires server-side token generation. | None |
pageType | The type of page the message appears on. Helps PayPal optimize messaging. Options: cart, checkout, home, mini-cart, product, product-details, product-listing, search-results. | None |
partnerAttributionId | An identifier for partner integrations. | None |
shopperSessionId | Represents the shopper's session. Format: 6B29FC40-CA47-1067-B21D-00DD010462DA. | None |
Cascading Style Sheet (CSS) properties
Customize the appearance of Pay Later messages using these CSS custom properties. Set these in your stylesheet targeting the paypal-message component.
| Property | Description | Default value |
|---|---|---|
--paypal-message-font-size | Font size for the message in px, from 10px to 16px. Values outside this range are clamped to the nearest valid value — for example, 4px uses 10px and 24px uses 16px. | 16px |
--paypal-message-text-align | Alignment of the message text. Options: left, right, center. | left |
Message styling
Customize how Pay Later messages appear on your site to match your brand. You can control appearance using CSS custom properties and logo and color configuration options.
Right-aligned, 16px font, logo on top:
<style>
paypal-message {
--paypal-message-font-size: 16px;
--paypal-message-text-align: right;
}
</style>
<paypal-message
auto-bootstrap
amount="300.00"
currency-code="USD"
logo-position="TOP"
></paypal-message>Centered, 10px font, inline logo:
<style>
paypal-message {
--paypal-message-font-size: 10px;
--paypal-message-text-align: center;
}
</style>
<paypal-message
auto-bootstrap
amount="300.00"
currency-code="USD"
logo-type="TEXT"
logo-position="INLINE"
></paypal-message>Prefixed, compact message:
<style>
paypal-message {
--paypal-message-font-size: 16px;
--paypal-message-text-align: right;
}
</style>
<paypal-message
auto-bootstrap
amount="300.00"
currency-code="USD"
alternative-prefix="LOWERCASE_OR"
message-length="COMPACT"
></paypal-message>Pay Later message examples
Preview different visual styles to choose the look that works best for your site. The following table shows the full range of visual styles available using the logo and color options described in this guide.
| Settings | Example |
|---|---|
logoType: "MONOGRAM" |  |
logoType: "MONOGRAM", textColor: "MONOCHROME" |  |
logoType: "MONOGRAM", textColor: "WHITE" |  |
logoType: "WORDMARK" |  |
logoType: "WORDMARK", textColor: "MONOCHROME" |  |
logoType: "WORDMARK", textColor: "WHITE" |  |
logoPosition: "INLINE", logoType: "WORDMARK" |  |
logoPosition: "INLINE", logoType: "WORDMARK", textColor: "MONOCHROME" |  |
logoPosition: "INLINE", logoType: "WORDMARK", textColor: "WHITE" |  |
logoType: "TEXT" |  |
logoType: "TEXT", textColor: "WHITE" |  |
logoType: "MONOGRAM" |  |
logoType: "MONOGRAM", textColor: "MONOCHROME" |  |
logoType: "MONOGRAM", textColor: "WHITE" |  |
logoType: "WORDMARK" |  |
logoType: "WORDMARK", textColor: "MONOCHROME" |  |
logoType: "WORDMARK", textColor: "WHITE" |  |
logoPosition: "INLINE", logoType: "WORDMARK" |  |
logoPosition: "INLINE", logoType: "WORDMARK", textColor: "MONOCHROME" |  |
logoPosition: "INLINE", logoType: "WORDMARK", textColor: "WHITE" |  |
logoType: "TEXT" |  |
logoType: "TEXT", textColor: "WHITE" |  |
Best practices
Follow these guidelines to optimize your Pay Later implementation for security, performance, and user experience.
Security and compliance
Choose Client ID or Client Token
Use clientId for most integrations — it's a public credential, safe to expose in frontend code, requires no server-side token generation, and is supported for all Messages SDK features.
Use clientToken only when your integration specifically requires it. This approach adds complexity and requires a backend endpoint to generate the token, but provides additional merchant control.
Manage data retention
PayPal automatically retains message interaction data for analytics and compliance. Do not store or duplicate this data locally unless required by your business logic.
Checklist before going live
Before deploying to production, verify the following:
- SDK scripts loaded (
coreandpaypal-messages) <paypal-message>component added to HTML- SDK instance created with valid
clientIdorclientToken - PayPal Messages instance created
- Message content fetched and displayed
- Amount updates tested with user interactions
- Learn More presentation configured (optional)
- Analytics callbacks implemented (optional)
- Message styling customized (optional)
- Sandbox testing completed with multiple amounts
- Load time monitoring configured
- Error handling implemented for network failures
- Lazy loading implemented (if applicable)
- Browser compatibility verified
- Responsive design tested across devices
- Production credentials configured
- Deployment to production verified
Related content
The following resources provide additional information and guidance for your Pay Later integration:
- Pay Later overview describes eligibility, offer types, and locale-specific offers.
- Pay Later integration guide provides a step-by-step guide for adding Pay Later messaging to your site.