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

On this page:

Script download

The script of the plugin is available at:

Embed it in your website by:

Html embedding

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

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": Open For "secondary": Open
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 1200.
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

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

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

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

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

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.

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

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

Below is an example implementation:

iziMobileLink

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

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 ();