Widget - frontend [ENG]

The InPost Pay plugin makes it possible to couple shopping baskets at the online stores of Merchants with the InPost app. The frontend layer is provided in the form of a JavaScript plugin for embedding on the website and this documentation. The backend layer provides data from two sources:

  1. details regarding the store's

  2. data related to InPost Pay provided by requests to InPost API.

The frontend layer assumes the use of the backend layer on the part of the Merchant only and none of the requests is to inquire the InPost API directly.

The correct integration requires delivering the layer of the Merchant Backend API in accordance with the above, the html embedding of the plugin, and deploying all the following methods in the frontend layer.

A list of methods to be implemented by the Merchant's backend, in order to use the plugin:

  • iziGetIsBound

  • iziGetOrderComplete

  • iziBindingDelete

  • iziCanBeBound

  • iziAddToCart

  • iziGetPayData

  • iziMobileLink

  • iziGetBrowserData

List of events which need to be implemented in order to use the plugin:

inpost-update-count


Script download

The script of the plugin is available at:

Embed it in your website by:

<script src="https://izi.inpost.pl/inpostizi.js"></script>

 

 

Html embedding

In order to display the widget, embed the following code in html:

<inpost-izi-button name="" masked_phone_number="" data-product-id="" language="pl" variant="primary" basket="true" dark_mode="true" count="5"></inpost-izi-button>

Parameter

Description

name

The buyer's forename, enter if the baskets are paired.

data-product-id

Product ID, required when you want to add a product with the stated ID to the basket at pairing.

masked_phone_number

Masked telephone number, required if the baskets are paired.

variant

Button appearance variant. Depending on the choice, the button may assume different styles.

The options available: "primary", "secondary"

Examples:

  • For "primary":

image-20240320-160701.png
  • For "secondary":

image-20240320-160727.png

 

basket

It determines whether or not the button is located on the basket's page. Acceptable value "true".

dark_mode

Specifies the display mode. Acceptable value "true".
Examples:
For: "true"

 

 

count

Specifies the initial number of products to be displayed upon coupling, (number of products currently in the basket).

binding_place

Specifies the site where the binding takes place. This notification goes to iziGetBindingData as a parameter.

  • PRODUCT_CARD - product card

  • BASKET_SUMMARY- basket summary

  • ORDER_CREATE - order creation stage

  • BASKET_POPUP - basket side panel

  • CHECKOUT_PAGE - checkout page

  • REGISTERFORM_PAGE - registerform page

  • MINICART_PAGE - minicart

Additionally, on the basis of this parameter, the code recognizes which copy version (texts and appearance) it should use.
Examples:
For: "PRODUCT_CARD":

For: "BASKET_SUMMARY"

  • THANK_YOU_PAGE * -this is not the site for binding, but for embedding the widget, which should assume the dedicated Thank You Page form upon placing the order.

max_width

Specifies the maximum width to be occupied by the widget. Attention: the widget adjusts the width to the container in which it is contained. If the master container has a width lower than max_width then the widget takes the dimensions of the master container. It is a good idea to apply an additional css min-width style directly to inpost-izi-button, which will help obtain the best adjusting results. It takes values between 220 and 600.

min_height

Specifies the minimum height to be occupied by the widget. It should accept values between 48 and 64.

frame_style

Optional parameter specifying the style of the widget's frame corner. By default, the widget is rectangular and if you want it to stay this way, do not provide this parameter. Available values:

  • rounded - small rounding

  • round - large rounding.


 

Displaying depending on the binding parameters

The status of binding is specified by the parameter basket_linked available in the InPost API. This is the only parameter which influences how the HTML widget should be displayed. If basket_linked=true then put the parameter masked_phone_number in HTML.

 

iziGetPayData

Downloads the data necessary to couple baskets. The prefix and phoneNumber parameters are not compulsory. The calls with 1 parameter are used to procure a qr code. The calls with all 3 parameters are used to couple using a phone number.
Note!
For a situation in which the backend has the following data:
browser_trusted = true
basket_linked = false
The backend should detect the key BrowserId available in the Cookies and perform Basket PUT with the current BrowserId instead of Binding POST.

In this situation, no confirmation return request takes place, and the correct data for iziGetPayData is an empty array.

Backend:

The Merchant's backend can receive the data required by inquiring InPost: GET/v1/izi/basket/{basketId}/binding

API

Parameters

prefix- phone number prefix
phonenumber - phone number
bindingPlace - binding place

Returns

Promise

Value

data from backend query GET/v1/izi/basket/{basketId}/binding

async function iziGetPayData(prefix, phoneNumber, bindingPlace) { return Promise.resolve({ qr_code: 'string', deep_link: 'string', deep_link_hms: 'string', } || []); }

Example implementation:

Response example:

  •   For a query without a number and prefix:
    {"qr_code":"iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABvUlEQVR4Xu2XsY3DMAxFaaRwmRG0ib2YAQvQYskmGsGlCyO8\/ynHuQRI+3MHRIVA66kgyE9SNn+37PXgWF\/yR0g2s7PXdcBmsZmdpKS4386lui9zheWweKYk4ZHDN3xfbK6r0VKTbKvZZLDKh8iWnJnqGSI9YX5yssFmXztnpn5nTkBCo4Ua3bdn9QpIrC0CEwrZT4QEvg1mqb8+LN5RkmSdt07hPESx3uMmI\/0NWWmBubBXdYdvGoLUXL11Chx6VGzzTUWiQU+2dgu2cTEEaxETVCdNhMj7G+4gREVKSu0v563JE20qJyhklhLUxhgyQVZAthQDREt6yhOboV3sRSMlyM8Y4oDFOxUT\/FCIhtRWFvAtNZlE3xSSjfnZEhxkfmxKrFgpKdQFHYzhzTrlHSUJjca0Rs8YWKfXx9yWkHi7wOLLAYdw8D6zdCTMnsrkG2K\/oyQxqVqdMj8RLCmJlVmnUCt94yNOSnL75p8Eq+RU12Oii0jhuNpsHdAuEKIo1pOWUKP8f+DMGlvR+AcIP5zzE2cfInyx1PCtveSUJJ4tNerU4w1h+9xWkUwzs0tPfLZgPalXQN6sL\/mv5AdSN8lx5hJUCgAAAABJRU5ErkJggg==",  "deep_link": "inpost:\/\/izilinkuat?binding_id=7953a3fd-698a-477e-ae44-5f8f1d75fdab", "deep_link_hms": "inpost:\/\/izilinkuat?binding_id=7953a3fd-698a-477e-ae44-5f8f1d75fdab", "basketId": "c01d1182-e445-4846-7336-538ea71f8588" }

  • For a query with a phone number and a prefix:
    {"basketId":"c01d1182-e445-4846-7336-538ea71f8588"}


 

iziGetBrowserData

The feature returns the browser information in the form of an object or an encoded Base64 string.

  • we can, for instance, make use of this function in iziGetPayData to transfer the browser data as an additional parameter to the backend

API

Parametry

  • base64 (boolean, optional): Specifies whether or not to return the data as an encoded Base64 string. By default set to false.

{ base64: true }

Zwraca

An object containing the browser data, or an encoded Base64 string with the browser data.

Wartość

  • user_agent (string): It includes a string of characters representing the agent of the browser user.

  • description (string): It contains a description of the browser app's code.

  • platform (string): It contains information about the browser platform.

  • architecture (string): It contains information about the version of the browser app.

 


 

iziGetIsBound

Called after clicking an uncoupled button to check and observe if the coupling was successful. On the developer's side, the communication must be handled so that the server is not loaded too much by applying websocket orr long pooling.
Backend:
The Merchant's backend can receive the data required by saving the data obtained from InPost in POST/v1/izi/basket/{backetId}/confirmation.

API

Parameters

none

Returns

Promise

Value

Data obtained from InPost Pay to the inquiry POST/v1/izi/basket/{basketId}/confirmation

Example implementation with the use of long pooling:

 


 

iziGetOrderComplete

The method called upon coupling a basket and on each page with a basket already coupled. Looks for the end of an order in the app or refreshing the page. As a reply, we get the URL of a page such as a thank you page with a thank you for the purchase message, or the notification of refreshing the page. The backend should react to events from the app and by sending only such actions as refresh or redirect.

Note!
In order to display InPost's acknowledgments, <inpost-thank-you/&gt must be embedded on the destination website,

Backend:
After creating an order at InPost's POST/v1/izi/order request, and sending the details of the order back to InPost, the Merchant's backend returns Promise.

API

 

Parameters

none

Returns

Promise

Value

{ action: ‘redirect’ | ‘refresh’ redirect?: ‘url’}

 


 

iziBindingDelete

This method is called during the unpairing process, to communicate with the backend of the merchandiser's system to remove the information related to the previously coupled number. This way, the user can conduct the process of coupling the number anew. This is crucial for managing the identities and ensures that the bindings are up-to-date and make it possible to reconfigure, when necessary.

Note for developers:

The iziBindingDelete function returns Promise, since it performs an asynchronous communication process with the server to ensure that some operations (such as removing cookies and other actions in the main code) are performed only after the successful completion of this asynchronous operation, use  the method .then (). And thus, you are sure that all the activities will be executed in the right order, and the entire process is more predictable and stable. When correctly performed, iziBindingDelete is only to signal the positive performance of the task and return an error in the case of errors.

Backend:

The Merchant's backend may remove the binding in the basket by inquiring InPost:

DELETE/v1/izi/basket/{basketId}/binding

 

Parameters

none

Returns

Promise

Value

void


 

iziCanBeBound

 

The method determines whether or not the product may be added to the basket and paired. Used for variable products in order to determine whether or not the product parameters have already been specified.

Parameters

productId - product identifier

Returns

Bool

Value

true || false

 


 

iziAddToCart

The iziAddToCart method initiates the process of adding a product to the basket. It is called before the stage of coupling in order to ensure that the basket is not empty, thus makes the coupling process possible. Note that this function is independent from the widget and the coupling process, and from the API interface, its main goal is to make coupling possible by ensuring that the basket is not empty.

API

Parameters

id - product identifier

Returns

void

Value

 


 

inpost - update - count

An event which makes it possible to update the number of products on the button. An event should be called at the time of adding products to the basket dynamically (without refreshing the page).

API

Parameters

{ detail: count } // int

Returns

 

Value

{ detail: 1 }

Below is an example implementation:

 


 

The method used to download a deeplink (for an already coupled basket) used to move to the mobile app.

The link should be generated on the side of the Merchant's backend.

We receive InPost_basket_id upon coupling with BA, therefore we should keep this id for the coupled basket.

Backend:
The Merchant's backend can receive the data required by saving the identifier of the basket from the InPost API (not the identifier of the Merchant's basket) from the request:
GET/v1/izi/basket/{basketId}/binding
and preparing the link according to the pseudocode:
switch (self::$environment) {
case self::ENVIRONMENT_PRODUCTION:
return 'inpost://izilink?basket_id=' + basketId;
case self::ENVIRONMENT_SANDBOX:
return 'inpost://izilinksandbox?basket_id=' + basketId;
default:
return 'inpost://izilinkuat?basket_id=' + basketId;
}

API

Parameters

none

Returns

Promise

Value

{
link: ‘url’
}

Example implementation:

 

Response example:

{ "link": "inpost:\/\/izilinkuat?basket_id=70db89ca-ad58-4863-8d95-0bdc9f75a3dc", }


 

SPA

The plugin has been developed for use with SPA applications. For the purpose of integrating the store with InPost Pay, the initiation of the Pay button must be handled within the app's life cycle.
After its first download, the script automatically initiates all the instances of <inpost-izi-button/> found in the code. To initiate the widget after updating DOM, use the method:

Below is an example for the ReactJs component:

 

There is a tag displaying the thank you for shopping message <inpost-thank-you/>. To initiate the acknowledgment after DOM is updated, use the method: window.handleThankYouNode ();