- Created by Paweł Milewski, last modified by Joanna Wołosz on Mar 28, 2024
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 11 Current »
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:
details regarding the store's
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:
Environment | Link |
Sandbox | |
Production |
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 |
| The buyer's forename, enter if the baskets are paired. |
| Product ID, required when you want to add a product with the stated ID to the basket at pairing. |
| Masked telephone number, required if the baskets are paired. |
| Button appearance variant. Depending on the choice, the button may assume different styles. The options available: "primary", "secondary" Examples:
![]()
![]() |
| It determines whether or not the button is located on the basket's page. Acceptable value "true". |
| Specifies the display mode. Acceptable value "true". ![]() ![]() |
| Specifies the initial number of products to be displayed upon coupling, (number of products currently in the basket). ![]() |
| Specifies the site where the binding takes place. This notification goes to iziGetBindingData as a parameter.
Additionally, on the basis of this parameter, the code recognizes which copy version (texts and appearance) it should use. ![]() For: "BASKET_SUMMARY" ![]()
|
| 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. |
| Specifies the minimum height to be occupied by the widget. It should accept values between 48 and 64. |
| 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:
|
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 |
|
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:
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 {}; } }
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 |
|
Zwraca | An object containing the browser data, or an encoded Base64 string with the browser data. |
Wartość |
|
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
Parameters | none |
Returns | Promise |
Value | Data obtained from InPost Pay to the inquiry POST/v1/izi/basket/{basketId}/confirmation |
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 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/> 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’} |
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 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 |
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.
Parameters |
|
Returns | Bool |
Value | true || false |
function iziCanBeBound(productId) { return 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 |
|
---|---|
Returns | void |
Value |
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
Parameters | { detail: count } // int |
Returns | |
Value | { detail: 1 } |
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
Parameters | none |
---|---|
Returns | Promise |
Value | { |
function iziMobileLink() { return Promise.resolve({ link: 'string' }) }
Example implementation:
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.
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:
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 ();
- No labels