Widget 2.0 [ENG]

Widget

The InPost Pay Widget is a JavaScript plugin embedded on the webpage by adding a script as in the example presented below:

<html>
<head>
  <script src="https://inpostpay-widget-v2.inpost.pl/inpostpay.widget.v2.js"></script>
</head>
<body>
<script type="application/javascript">
  const widgetOptions = {
    merchantClientId: 'b73ca9fc-0123-4567-8912-5ac02c6af6e9',
    basketBindingApiKey: 'QdMW9xtB9POfNG7GiGIO4EFPEKSvzOuW',
    unboundWidgetClicked: (productId) => new Promise()
  };
  const widget = InPostPayWidget.init(widgetOptions);
</script>
...
<inpost-izi-button data-product-id="123" binding_place="PRODUCT_CARD" variation="..." ></inpost-izi-button>
...
</body>

Environments:

Merchant Client Id Id is a value assigned by InPost.

Prod - the Merchant Client Id value for the production environment may be obtained in the merchant panel by following the Merchant account configuration - production environment instruction.
Sandbox - in order to obtain a value for the Sandbox environment, it is necessary to send a request to integracjapay@inpost.pl.

By default, Widget 2.0 may be called from the domain defined on the merchant account as home page. If the merchant calls the widget from a different domain, it is necessary to add an appropriate URL address as custom origin. For this purpose, it is necessary to send a request to integracjapay@inpost.pl, indicating the appropriate URL address in the body of the message.

On this page:

1 Widget
2 Lifecycle notes
3 Specification
4 Widget placeholder
5 Sequence diagrams for InPost Pay and Widget 2.0

Want to test on the local environment?

In order to provide remote access to the local environment, an additional workaround is required in the form of tunneling traffic from the public domain to a local address. Without such a workaround, there is no way to connect directly to the local environment.
Recommended solution
The current recommended tool is ngrok, which allows you to quickly set up a tunnel between the public URL and the local environment. All you need is a free account that provides one permanent public domain. This domain can redirect traffic to a local application or a closed test environment.
Requirements
After creating a free public domain, you need to provide its address in the Contact -> Sandbox form to receive credentials and all test traffic can be routed to that address.

Lifecycle notes

There could be only one widget instance per page, since we offer only one kind of placeholder and widget can't distinguish and apply different configuration
It's up to merchant when to initialise the widget, depending when widget placeholder is added to DOM or configuration becomes available, so can be done at root level (as above) or can be deferred and called after some async actions
Widget's lifecycle:
1. right after initialisation, it'll retrieve its configuration from WidgetAPI for given merchantId
2. if basketBindingApiKey is provided as string or undefined - it'll make a call to Widget API to get basket binding status
3. if basketBindingApiKey is provided as promise - it'll first await for promise to resolve and only then make a call to Widget API to get basket binding status
4. once page is fully loaded and call to Widget API is made, it will check if any placeholder is present on the DOM and render the widget in appropriate state

Specification

export type BasketBindingApiKey = undefined | string | Promise<string>

export type WidgetBasketEvent =
  | 'basketDeleted'
  | 'basketProductChanged'
  | 'orderCreated'

export type WidgetBasketEventHandler = (
  event: WidgetBasketEvent,
) => boolean | Promise<boolean>

export interface WidgetInitOptions {
  /**
   * Merchant Client Id.
   */
  merchantClientId: string
  /**
   * Unique basket binding API key - it's obtained from InpostPay API.
   * If it's known at the page render: can be provided as string.
   * If it can be resolved during page load: can be a promise.
   * Otherwise: 'undefined', widget will assume that basket is not bound, because it can't check basket binding status without knowing api key.
   * And in such case, it's mandatory for 'unboundWidgetClicked' to return a 'apiKey', otherwise baskets can't be bound.
   */
  basketBindingApiKey: BasketBindingApiKey
  /**
   * This callback function is mandatory for unbound basket and for binding_place=PRODUCT_CARD.
   * It'll be called to add the product to merchant's basket when user clicks on the widget.
   * When the promise is rejected with Error('UNDELIVERABLE_PRODUCT') widget won't show error popup or binding popup.
   * @return promise with 'basketBindingApiKey'
   */
  unboundWidgetClicked?: (productId?: string) => Promise<string>
  /**
   * Callback function to reflect basket updates on merchant's page.
   * If not provided or returning false - widget will refresh the entire page.
   * @return 'true' if widget should not refresh the page.
   */
  handleBasketEvent?: WidgetBasketEventHandler
  /**
   * Widget-API base url used for frontend to API communication.
   * By default, https://inpostpay-widget-api.inpost.pl is used.
   */
  apiBaseUrl?: string
  /**
   * If set to true BrowserId will be persisted and read from localStorage.
   * If set to true the app will always try to open a https deep link, if false the deep link url
   * will be deducted based on the UserAgent.
   * Default: false
   */
  webView?: boolean
  /**
   * Custom language. By default, widget will use browser's language and 'pl' as fallback
   */
  language?: string
}

export interface InPostPayWidget {
  refresh: (options?: Partial<WidgetInitOptions>) => void
}

export interface InPostPayWidgetNamespace {
  init: (options: WidgetInitOptions) => InPostPayWidget
}

declare global {
  export interface Window {
    InPostPayWidget: InPostPayWidgetNamespace
    __INPOST_PAY_WIDGET__?: InPostPayWidget
  }
}

declare function initialiseInpostPayWidget(
  options: WidgetInitOptions,
): InPostPayWidget

Widget placeholder

In order to correctly position widget buttons, the code below must added to the webpage in the appropriate place (under the “Add to basket” button or next to “Checkout”)

<inpost-izi-button data-product-id="" binding_place="" variation="" ></inpost-izi-button>

The placeholder supports the following parameters:

Parameter	Required	Description	Additional remarks

Parameter

Required

Description

Additional remarks

binding_place

Yes

Specifies where the widget is embedded on the page.

Possible values:

PRODUCT_CARD
BASKET_SUMMARY
ORDER_CREATE
BASKET_POPUP
THANK_YOU_PAGE
CHECKOUT_PAGE
MINICART_PAGE
REGISTERFORM_PAGE
LOGIN_PAGE

data-product-id

Yes, if binding_place=”PRODUCT_CARD”

variation

No

A list of styles, e.g.

"dark primary size-md rounded"

If color and size are not specified, the widget defaults to "secondary size-lg".

Available styles, by category:

Widget frame style:

round - large widget border radius
rounded - small widget border radius (border radius 8px).

If both are specified, round takes priority over rounded. If neither is specified, the widget has square frames.

Text color below the button:

dark - text under the button is white

If dark is not specified, the text below the widget is black.

Widget color:

primary - yellow widget color
secondary - black widget color

Predefined widget sizes:

size-xs
size-sm
size-md
size-lg
size-xl

If more than one size is specified, the smaller one takes priority.

In order to display the "Thank You Page" <inpost-thank-you></inpost-thank-you> must be added in the appropriate place on the webpage with the thank you for the order.

Sequence diagrams for InPost Pay and Widget 2.0

The articles below contain sequence diagrams for InPost Pay and Widget 2.0.