Skip to main content

Loading the PlanPay Checkout Widget

In the previous section, Creating a Checkout, we explained how to create a checkout object and obtain its unique ID through an API call.

Now, we'll show you how to load the PlanPay widget onto your website using the obtained checkout ID. There are two ways to achieve this:

After completing 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.

PlanPay checkout widget

info

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

When the customer clicks the "Pay in installments" (i.e., PlanPay) button, they will be redirected to a PlanPay-hosted page to sign up/sign in and complete their checkout. We will cover the testing experience in the next section.

Loading the Checkout 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.checkout 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.

Loading the Checkout Widget​

After initializing the PlanPay module as described in the previous section, you can load the checkout widget onto your page by adding the following HTML code, which can be rendered using any web framework or library (e.g., React, Angular, Vue):

<div data-planpay-checkout-id="n1083c79a35b">
  Loading...
  <!-- Optional "loading" content -->
</div>

Replace n1083c79a35b with the actual checkout ID created using the API call described in Creating a Checkout.

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

planpay.checkout.refresh();

This will load or reload the PlanPay checkout into any element that has the data-planpay-checkout-id attribute, replacing any loader content.

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 Checkout 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 adding the HTML markup and loading the PlanPay JavaScript SDK onto the page.

To get started, you will need to add an HTML element, such as a div, where the PlanPay widget will display. This element must have the data-planpay-checkout-id attribute with a value set to the checkout ID property of the checkout API response. For example:

<div data-planpay-checkout-id="n1083c79a35b">Loading...</div>

Replace n1083c79a35b with the actual checkout ID created using the API call described in Creating a Checkout.

Next, load the Planpay JavaScript SDK onto the page using the scriptUrl property from the checkout object. 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 checkout widget
  window.PlanPaySDK.checkout.refresh();
</script>

This will load or reload the PlanPay checkout into any element that has the data-planpay-checkout-id attribute, 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.

Handling widget load errors​

there is an error in the API response, the widget will still appear, but it may display a message that requires the user's attention.

For example, if the user tries to purchase an item that is not eligible for PlanPay, the widget may show a message like:

PlanPay is not available for this purchase within 30 days of travel.

In such cases, the user may need to take some action based on the message. For instance, they may choose a different product or adjust the purchase date. The widget will provide appropriate guidance to the user.

If the error cannot be remedied, the message will be more general, like:

PlanPay is not available for this purchase.

Note that the widget takes care of displaying the message and guiding the user.