Advanced JavaScript options

SDKCurrentLast updated: November 9th 2023, @ 9:11:16 am


The messages component of the JavaScript SDK can be integrated in a variety of ways. The following sections cover different methods for configuring and using the SDK.

Know before you code

This integration modifies an existing Pay Later integration.

Configure using JavaScript

You can configure and display Pay Later messages using JavaScript as an alternative to HTML attributes. The JavaScript SDK messages component uses an API that is similar to the API used by the buttons component.

The following code sample shows how to create a message object by calling the paypal.Messages function. The paypal.Messages function takes a configuration object as its only argument and returns a message object.

The message object has a render() function that accepts an argument that defines the element in which messages are rendered. In this example, .pp-message is a CSS selector string, but you can also use an HTMLElement reference, or an array of HTMLElement references.

Sample code

1<head>
2 <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=messages"></script>
3</head>
4<body>
5 <div class="pp-message"></div>
6 <script>
7 paypal
8 .Messages({
9 amount: 500,
10 placement: "product",
11 style: {
12 layout: "text",
13 logo: {
14 type: "inline",
15 },
16 },
17 })
18 .render('.pp-message');
19 </script>
20</body>

In the code sample:

  • The amount is set to 500.
  • The message is added to the details of a product, so placement: "product" is added to the configuration object.
  • The message uses a text layout with a primary logo on top of the message.
  • The SDK renders the message inside any element that contains a class attribute with the value .pp-message.

The configuration object accepted by the Messages function mirrors the HTML attributes that are parsed and read from the elements targeted for messages. For example, data-pp-style-layout is the same as the configuration object path of style.layout. See the Reference table to view all the configuration settings and their associated attributes and object keys.

Note: Both inline attributes and the JavaScript configuration object can be used independently or combined to change the message configuration. If there are conflicting settings, the inline HTML attribute setting overrides the JavaScript configuration object setting.

Use event hooks

The messages component of the PayPal JavaScript API lets you to pass in callback functions, which are triggered on certain events. The available events to hook into are onRender, onClick, and onApply.

EventDescription
onRenderInvoked after each message has been successfully rendered into the DOM
onClickInvoked after a message has been selected
onApplyInvoked after user selects the Apply button or link in the pop-up modal

One common use case for event hooks is to send data to your own analytics platform. For example, you might have your own custom data processing, or you might use a third-party analytics provider.

To add logic to these event hooks, add a function to the associated key of the configuration object you pass to paypal.Messages().

The following code sample calls the paypal.Messages function to create a message object with optional properties for onRender, onClick, and onApply. When any of these events happen, the associated callback function is triggered. When the message is rendered, "Callback called on render" is logged in the console.

Sample code

1<head>
2 <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=messages"></script>
3</head>
4<body>
5 <div class="pp-message"></div>
6 <script>
7 paypal
8 .Messages({
9 amount: 500,
10 placement: "product",
11 style: {
12 layout: "text",
13 logo: {
14 type: "inline",
15 },
16 },
17 onRender: () => {
18 console.log("Callback called on render");
19 // such as send a "render event" to your analytics platform.
20 },
21 onClick: () => {
22 console.log("Callback called on click");
23 // such as send a "click event" to your analytics platform.
24 },
25 onApply: () => {
26 console.log("Callback called on apply");
27 // such as send an "apply event" to your analytics platform.
28 },
29 })
30 .render('.pp-message');
31 </script>
32</body>

Use namespace attributes

Select this option if you're using a legacy integration for PayPal Checkout that uses the data-namespace attribute when loading the JavaScript SDK messages component.

Sample code

1<script
2 data-namespace="PayPalSDK"
3 src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=messages"
4></script>

If you're configuring messages using JavaScript, the value you set for data-namespace is the name of the global variable you use to configure and render messages. In this example, "PayPalSDK" is used in the data-namespace.

Sample code

1<head>
2 <script
3 data-namespace="PayPalSDK"
4 src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=messages"
5 ></script>
6</head>
7<body>
8 <div class="pp-messsage"></div>
9 <script>
10 PayPalSDK.Messages({
11 amount: 500,
12 style: {
13 layout: "text",
14 logo: {
15 type: "inline",
16 },
17 },
18 }).render('.pp-message');
19 </script>
20</body>

For more information about namespaces and compatibility with Checkout integrations, see upgrade to existing integration.

Render multiple messages

The SDK renders a message into any element with a data-pp-message attribute or elements that match the target you defined in the JavaScript configuration using the Messages() function. If there is a conflict between inline HTML attributes and the JavaScript configuration, inline elements will be used.

You can use both inline attributes and JavaScript. For example, you can use the JavaScript configuration to declare shared or common settings, while you can use inline attributes to customize a specific message.

Sample code

1<head>
2 <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=messages"></script>
3</head>
4<body>
5 // Example list of products
6 <ul class="listings">
7 <li class="listing">
8 <div class="listing__content">
9 <div class="listing__title">Product Name 1</div>
10 <div class="listing__price">$50</div>
11 </div>
12 <div class="pp-message">
13 // Pay Later message will be inserted here
14 </div>
15 </li>
16 <li class="listing">
17 <div class="listing__content">
18 <div class="listing__title">Product Name 2</div>
19 <div class="listing__price">$100</div>
20 </div>
21 <div class="pp-message">
22 // Pay Later message will be inserted here
23 </div>
24 </li>
25 </ul>
26 <script>
27 // Grab all product listings on the page
28 const listings = Array.from(document.querySelectorAll(".listing"));
29 // Loop through each product listing
30 listings.forEach((listing) => {
31 // Extract the price of the product by grabbing the text content of the
32 // element that contains the price. Use .slice(1) to remove the leading
33 // $ sign
34 const price = Number(
35 listing.querySelector(".listing__price").textContent.slice(1)
36 );
37 // Grab child element of this .listing element that has the
38 // pp-message classname
39 const messageElement = listing.querySelector('.pp-message');
40 // Set data-pp-amount on this element. The PayPal SDK monitors
41 // message elements for changes to its attributes, so the
42 // message is updated automatically to reflect this amount.
43 messageElement.setAttribute("data-pp-amount", price);
44 });
45 // Render all Pay Later messages
46 paypal
47 .Messages({
48 style: {
49 layout: "text",
50 logo: {
51 type: "primary",
52 position: "top",
53 },
54 },
55 })
56 .render('.pp-message');
57 </script>
58</body>

Update messages without reloading the page

The SDK's messages component attaches observers to all attributes that start with data-pp on DOM elements targeted with a message. Changing an attribute can change data-pp-amount from 100 to 200, such as if a customer updates the item's quantity in their cart.

Don't call the render() function again because the SDK automatically detects the change and renders a new message if necessary.

If new HTML content is dynamically injected to the document and you want to render a message inside this new HTML, call the render() function of paypal.Messages again.

Integrate into a single page app

The JavaScript SDK should only be loaded once. Add the <script/> tag into the <head/> of your main HTML document into which you inject your client-side app.

Don't reload the SDK on state changes or route updates. If the state or routes in your single-page application change enough to render new content and new messages, call paypal.Messages.render() again and specify the new targets for the messages.

Reference

Pay Later configuration reference