Widget 2.0 [ENG]
Widget
InPost Pay widget is a JavaScript plugin that is embedded into a webpage by adding the following exemplary script:
<html>
<head>
<script src="https://inpostpay-widget-v2.inpost.pl/inpostpay.widget.v2.js"/>
</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:
Sandbox - https://sandbox-inpostpay-widget-v2.inpost.pl/inpostpay.widget.v2.js
Prod - https://inpostpay-widget-v2.inpost.pl/inpostpay.widget.v2.js
Merchant Client Id can be obtained by writing at integracjapay@inpost.pl.
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:
right after initialisation, it'll retrieve its configuration from WidgetAPI for given merchantId
if basketBindingApiKey is provided as string or undefined - it'll make a call to Widget API to get basket binding status
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
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.
* @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://api.inpost.pl will be used as a fallback.
*/
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
To correctly position widget button(s), the following placeholder tag should be added to the webpage in the appropriate place(s) (near "Add to cart" button or "Checkout").
<inpost-izi-button data-product-id="" binding_place="" variation="" ></inpost-izi-button>
The placeholder supports the following attributes:
Parametrer | Required | Description | Additional remarks |
---|---|---|---|
| yes | possible values are:Â
| Â |
| if binding_place=PRODUCT_CARD | Â | Â |
| no | a list of styles, ie "dark primary size-m rounded" default: "secondary size-l" | supported styles:
|
Â
Sequence diagrams for InPost Pay and Widget 2.0
Â
Â
Â