Advanced JavaScript Options

SDKCurrentDirect Merchant

Last updated: Apr 9th, 8:51pm

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.

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.

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        pageType: "product-details",
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 pageType: "product-details" 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.

Event

Description

Invoked after each message has been successfully rendered into the DOMonRender
Invoked after a message has been selectedonClick
Invoked after user selects the Apply button or link in the pop-up modalonApply

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        pageType: "product-details",
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.

Know before you code

This integration modifies an existing Pay Later integration

Required
This integration modifies an existing Pay Later integration

Learn More