Page Comparison

The InPost Pay widget offers coupling plugin makes it possible to couple shopping baskets at the online stores of Merchants with the InPost Mobile applicationapp. The frontend layer is delivered provided in the form of a JavaScript plug plugin for embedding on the website , and of this documentation. A correct integration requires providing a backend layer, 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 plugplugin, and control over the status of the front-end layer by providing the methods described below.

deploying all the following methods in the frontend layer.

A list of methods to be implemented by the merchantMerchant's backend, in order to use the plugplugin:● iziGetBindingData
●

• 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 plug 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.

"Secondary" or "primary" available.

The options available: "primary", "secondary" Examples: For "primary": Image Added For "secondary": Image Added
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" Image Added Image Added
count	Specifies the initial number of products to be displayed upon coupling, (number of products currently in the basket). Image Added
binding_place	Specifies the site where the

bind occurs

binding takes place. This

information

notification goes to iziGetBindingData as a parameter.

Available options are:

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": Image Added For: "BASKET_SUMMARY" Image Added THANK_YOU_PAGE

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 pair 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 pair couple using a phone number.
Note!
For a situation in which the backend has the following data:

Parameters

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

async function 

iziGetPayData(

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

Example implementation:

async function iziGetPayData(prefix, phoneNumber, bindingPlace) {
const url = 'http://example.com/endpoint';
const browserData = window.iziGetBrowserData({ base64: true });
const data = {
prefix: prefix || "",
number: phoneNumber || "",
browser: browserData,
binding_place: bindingPlace
};
try {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(data),
});
if (!response.ok) {
throw new Error('Network response was not ok');
}
return response.json();
} catch (error) {
return {};
}
}

iziGetIsBound

Calls after displaying a qr code or a deep link in order to check whether 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

const browserData = window.iziGetBrowserData({ base64: true });

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

function iziGetIsBound() {
return Promise.resolve({
"phone_number": {
"country_prefix": "string",
"phone": "string"

},
"browser": {
"browser_trusted": boolean,
"browser_id": "string",
},
"name": "string",
"surname": "string"
"masked_phone_number": "string"
});
}

Example implementation with the use of long pooling:

let timeoutId;//A variable for storing timeout identifier
/**
* it serves different server actions.
* @param {string} action - Type of actions to be performed.
* @param {Function} resolve- Promise solution function.
* @param {Function} reject - Promise rejection function.
*/
function handleServerAction(action, resolve, reject) {
if (timeoutId) {
clearTimeout (timeoutId);//If an active timeout exists, it cleans
 it.
}
switch (action) {
case 'close':
// Rejects a promise with an error, if the server returns the "close" action
reject (new Error ("Connected interrupted, try
again."));
break;
case 'retry':
//Sets new timeout to reset a long
polling, if the server returns the "retry" action
timeoutId = setTimeout(() => setupLongPolling(resolve, reject),
1000);
break;
default:
break;//Does nothing for other actions
}
}
/**
* Sets a long polling for the server.
* @param {Function} resolve- Promise solution function.
* @param {Function} reject - Promise rejection function.
*/
async function setupLongPolling(resolve, reject) {
try {
//Sends an inquiry to the server
const response = await
fetch(/wp-json/inpost/v1/izi/merchant/basket/confirmation);
const data = await response.json ();//Converts the response: to
format JSON
//Checks the response from the server, and undertakes proper actions
if (data?.phone_number) {
resolve (data);// Solves the promise, if receives a number
phone
} else if (data?.action) {
handleServerAction (data.action, resolve, reject);//Handles
the server actions, if receives an action
} else if (data?.error_code) {
reject(new Error (data.error_code));// Rejects a promise
with an error, if receives an error code
} else {
//If receives neither phone number, nor actions, nor error code
, sets a new timeout for a long polling
timeoutId = setTimeout(() => setupLongPolling(resolve, reject),
10000);
}
} catch (error) {
reject (error);// Rejects a promise with an error in the case of an error
}
}
/**
* Function, which uses a long polling to learn
if it is associated with a phone number.
* @returns {Promise} - A promise associated with the server's response.
*/
async function iziGetIsBound() {
return new Promise((resolve, reject) => {
setupLongPolling (resolve, reject);//Activates long polling
});
}
export default iziGetIsBound;//Exports the function as a default
export

iziGetOrderComplete

The method called upon pairing coupling a basket and on each page with a basket already pairedcoupled. Looks for the finish end of ordering 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

function iziGetOrderComplete() {
return Promise.resolve({
action: 'string'
redirect: 'string'
})
}

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 method called at pairing removal.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

function iziBindingDelete() {
return Promise.resolve();
}

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.

function iziCanBeBound(productId) {
return true || false;
}

iziAddToCart

The method used to add a product after clicking on the widget.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

async function iziAddToCart(id) {
return void;
}

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:

jQuery(document.body).on(eventName, () => {
const countContainer = document.getElementById(elementID);
if (!countContainer) return;
const count = parseInt(countContainer.textContent.trim(), 10);
if (isNaN(count)) return;
const event = new CustomEvent("inpost-update-count", { detail: count
});
const iziButtonsCollection =
Array.from(document.getElementsByTagName("inpost-izi-button"));
iziButtonsCollection.forEach(el => el.dispatchEvent(event));
});

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

function iziMobileLink() {
return Promise.resolve({
link: 'string'
})
}

Example implementation:

SPA

export default async function iziMobileLink() {
const url = "http://example.com/endpoint";
try {
const response = await fetch(url);
if (!response.ok) {
throw new Error('Network response was not ok');
}
const data = await response.json();
return data;
} catch (error) {
throw error;
}
}

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.
Upon After its first loadingdownload, the script automatically initiates all the instances of <inpost-izi-button/> W found in the code to . To initiate the widget after updating DOM update
, use the method:

window.handleInpostIziButtons();

Below is an example for the ReactJs component:

import React, { useEffect } from "react";
import { useLocation } from "react-router-dom";

export...= ({ children }) => {
const location = useLocation();
useEffect(() => {
window.handleInpostIziButtons();
}, [location]);
return <>{children}</>;
};

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