Loading the PlanPay Price-Preview Widget

In the previous section, we looked at where the widget should be loaded on the merchant's website. In this section, we'll look at the process for performing this integration.

There are two parts to adding the price-preview widget to a page:

• Add the Required Target Markup to the Page
• Select an Integration Pathway

Once you have added this markup and completed one of these integration pathways, you'll be able to load the PlanPay checkout widget onto your website. The widget will look like the screenshot below.

info

Note: the widget layout is fully responsive and renders well above 320px resolution.

Add the Required Target Markup to the Page

Both integration pathways require the addition of the following HTML markup as a target for each price-preview widget. Place it within the product-listing or search-result section where the price-preview is intended to appear. Sample attribute values are provided below for reference.

<div data-planpay-data-type="price-preview"
    data-planpay-total-cost="200.00"
    data-planpay-currency-code="AUD"
    data-planpay-redemption-date="2025-03-30"
    data-planpay-payment-deadline="60"
    data-planpay-total-minimum-deposit="20.00"
    data-planpay-merchant-id="dhj987l">
  Loading...
  <!-- Optional "loading" content -->
</div>

info

The "Loading..." comment is an optional placeholder that can be displayed while the contents of the div are being loaded.

Refer to the attribute table below for more details.

Attribute	Description	Required
data-planpay-data-type	The type of PlanPay data for the element, in this case price-preview
data-planpay-total-cost	The total cost of the item or items being purchased	✔️
data-planpay-currency-code	The currency code for the transaction	✔️
data-planpay-redemption-date	The date the customer will redeem the item or service	✔️
data-planpay-payment-deadline	The number of days the customer has to complete payments
data-planpay-total-minimum-deposit	The minimum deposit required for the purchase
data-planpay-merchant-id	The unique identifier assigned to the merchant by PlanPay	✔️
data-planpay-frequency	The frequency of installment payments (optional). Valid options: 'Weekly' (default), 'Fortnightly', or 'Monthly'.
data-planpay-mode	Determines the widget color mode. Options: 'light' or 'dark'. Optional. Defaults to 'light'.
data-planpay-size	Determines the widget scale. Options: 'x-small', 'small', 'medium', 'large'. Optional. Defaults to 'large'.
data-planpay-layout	Determines the stacking of widget elements. Options: 'horizontal' or 'vertical'. Optional. Defaults to 'horizontal'.
data-planpay-variant	Determines the border and background style. Options: 'contained', 'text', 'outlined'. Optional. Defaults to 'contained'.

Example layouts

tip

Below are example widget layout configurations shown in size order of x-small, small, medium, large.

Select an Integration Pathway

Once the price-preview target markup has been added to the page, an integration path must be selected. Each integration path will result in scripts being added to the page that will replace the target markup with a price-preview widget. There are two supported integration paths.

• Recommended: Loading the Price-Preview Widget with @planpay/web
• Legacy: Loading the Price-Preview Widget with Vanilla JavaScript and HTML markup

Loading the Price-Preview Widget with @planpay/web

tip

This is the recommended approach.

The @planpay/web package provides an easy way to interact with the PlanPay JavaScript SDK, simplifying the integration process for websites built with TypeScript or ES6+. This includes loading the SDK into various frameworks, including React, Angular, and vanilla JS sites. The module automates the following:

• Loading the PlanPay JavaScript SDK
• Providing auto-complete support for your code to simplify integration
• Keeping your integration up to date with the latest versions of the PlanPay widgets

Installation

Using NPM:

npm i @planpay/web

Using Yarn:

yarn add @planpay/web

Basic Usage

To use any of the methods, you must first initialize the PlanPay web components library by calling the planpay.init({...}) method. After that, you can call the .refresh({...}) method of the planpay.pricePreview objects to refresh or load the checkout widget.

Initializing the Module

To initialize the widget, use the following code with the provided options.

Production (prod)

// Initialize the PlanPay Web Components library with default options.
// This will manage the loading of the PlanPay JavaScript SDK onto the current page.
import { planpay } from '@planpay/web';

// To explicitly target the sandbox environment, pass the `environment` option as `sbx`.
// For the production environment, no option needs to be provided OR
// you may optionally pass the `environment` option as `prod`.
planpay.init();

Sandbox (sbx)

import { planpay } from '@planpay/web';

// To target the sandbox (sbx) environment, provide the 'sbx' value for the environment.
planpay.init({
  environment: 'sbx',
  showDebug: true,
});

info

Note: the showDebug property can be set to true to provide verbose debug logs in the browser console, which can be useful during development.

Once this HTML code is on the page, you can load the price-preview widget by calling:

planpay.pricePreview.refresh();

This will load or reload the PlanPay checkout into any element that has the data-planpay-data-type="price-preview" attribute, replacing any loader content.

This method accepts an arguments object, where the targetElement property is set to a valid CSS selector or HTML element representing the parent element of the price-preview markup. For instance:

planpay.pricePreview.refresh({
  targetElement: '.search-results',
});

The targetElement option should select the element that contains all the child elements of the price-preview markup. For instance, if the price-preview markup is included in each search-result item on a search-results page, the targetElement CSS selector should target the element that encloses all the search-result items. If targetElement is not provided, all elements in the document will be targeted for updates. This option can be useful to update only specific parts of the price-preview markup after an AJAX load or similar actions.

Fetching the price-preview raw values

info

Note: This feature is available in @planpay/web version 0.1.4 and later.

It is possible to fetch the raw values for the preview like so.

planpay.pricePreview.fetch({
  totalCost: 1000,
  merchantId: 'dhj987l',
  redemptionDate: '2023-12-30',
  currencyCode: 'AUD',
  frequency: 'Weekly', // Optional. Defaults to `'Weekly'`.
});

tip

The frequency argument is optional, with a default value of 'Weekly'. The other valid options are 'Monthly' and 'Fortnightly'.

When the request is successful, it will return the installment amount and the frequency as object with the following structure.

{
    installmentAmount: 15.00,
    frequency: 'Weekly',
    currencyCode: 'AUD'
}

If the request is successful, it will return an error message like so,

{
  error: {
    messages: ['totalCost must be > 0.'];
  }
}

This functionality enhances your ability to access and utilize raw price-preview data for your integration needs.

Tips for Integrating with Front-End Frameworks

When using the @planpay/web module, the PlanPay JavaScript SDK is loaded from the PlanPay servers onto every target page when the planpay.init() method is called. This helps to ensure that widget integrations keep up to date with the latest changes. However, it can create challenges with certain front-end frameworks like React.

To call the method only after the content has rendered, lookup the appropriate component or page event for your library. Here are some examples:

React

Add the PlanPay method calls via the useEffect(...) hook.

useEffect(() => {
  // PlanPay init and other method calls here...
}, []);

Angular

Add the PlanPay method calls via the ngAfterContentInit(...) hook.

ngAfterContentInit() {
  // PlanPay init and other method calls here...
}

Loading the Price-Preview Widget with Vanilla JavaScript and HTML markup

caution

While this legacy approach is still supported, it may not receive the same level of ongoing maintenance and support as the recommended approach using @planpay/web. If possible, use the recommended approach for the best long-term stability and compatibility with future updates.

This approach involves manually loading the PlanPay JavaScript SDK onto the page. This can be achieved with a script tag, as follows:

<!-- Omit .sbx from the URL in production -->
<script src="https://sdk-app.sbx.planpay.com/planpay-sdk.js"></script>
<script>
  // Call this function to load or reload the price-preview widget
  window.PlanPaySDK.pricePreview.refresh({});
</script>

This will load or refresh the PlanPay price-preview into any element that has the data-planpay-data-type="price-preview", replacing any loader content.

info

The URL to load the PlanPay widget SDK will vary depending on the environment for the request. In the example above, the .sbx prefix was included in the URL because this was the sandbox environment. For the production environment, the URL is https://sdk-app.planpay.com/planpay-sdk.js without the prefix. Make sure to use the correct URL for your environment.