Advanced JavaScript options

SDKCurrent

Last updated: Apr 3rd, 5:09pm

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

Required
This integration modifies an existing Pay Later integration

This integration modifies an existing Pay Later integration.

Configure using JavaScript

You can configure and render your messages using JavaScript as an alternative to HTML attributes. The PayPal JavaScript SDK messages component uses a JavaScript API that is similar to the API used by the buttons component.

1<!DOCTYPE html>
2
3<head>
4  <meta name="viewport" content="width=device-width, initial-scale=1">
5  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
6  <script
7    src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID&currency=EUR&components=messages">
8  </script>
9</head>
10<body>
11
12<div class="pp-message"></div>
13  <script>
14    paypal.Messages({
15      amount: 120,
16      style: {
17        layout: 'text',
18        logo: {
19          type: 'primary'
20        }
21      }
22    })
23    .render('.pp-message');
24  </script>
25</body>

In the sample code, you 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 into which element(s) it should render messages. render() accepts a CSS selector string (such as .pp-message), an HTMLElement reference or an array of HTMLElement references. Invoking the render() function makes the SDK render messages on your page in the specified target elements.

In the code sample,

The amount is set to 500.

The message is added to a product detail, 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 an 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 equivalent to 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.

Event	Description
onRender	Invoked after each message has been successfully rendered into the DOM
onClick	Invoked after a message has been selected
onApply	Invoked 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>

In this example, you create a message object by calling the paypal.Messages function like in the previous example. However, in this example, you add optional properties for onRender, onClick, and onApply. When any of these events happen, the associated callback function is invoked. For example, when the message is rendered, there is a log in the console "Callback called on render".

Use namespace attributes

If you're using a legacy integration for PayPal checkout, you might be using the data-namespace attribute when loading the PayPal JavaScript SDK messages component.

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.

Example:

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-message"></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 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.

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. In many cases, you should add the <script/> tag into the <head/> of your main HTML document into which you inject your client-side app (this HTML is often called index.html). Make sure to not reload the SDK on state changes or router updates. If the state or routes in your SPA change enough to render new content and new messages, invoke paypal.Messages.render() again and specify the new targets for the messages.

Reference

See Reference tables for more details on available options.