Developer DocumentationsSequence diagrams for InPost Pay & Widget

Sequence diagrams for InPost Pay & Widget

Owned by Michał Machowski
Last updated: May 25, 2023

UC.01 basket linked with InPost Pay

 

Verification of the association between the shopping basket and InPost Pay [1-11]:

  1. The Client moves to the Merchant's website

  2. The Merchant builds the store's website, while verifying whether or not the customer's basket is linked with InPost Pay, and whether or not the browser the customer currently uses is among the trusted ones. The verification takes place through the request GET/v1/izi/basket/{basket_id}/binding to InPost Pay

  3. InPost Pay returns the information that the basket is linked (basket_linked=true), and the browser is trusted (browser_trusted=true)

  4. The Merchant builds the store's website with an embedded widget with the message: "Zamów i zapłać. Twoje produkty czekają w aplikacji InPost!” (Order and pay. Your products await in InPost App) 

  5. After obtaining the information that the basket is linked, the widget starts observing the Merchant's backend (with the use of looping, or websocket), to see if the order for the basket was realized. Upon receiving the information of the completion, the widget presents the screen with thanks for placing the order.

Assigning the basket to another phone number (Removing /desynchronizing the basket associated with InPost Pay) [12-22]:

  1. The Customer presses the widget "Zamów i zapłać z InPost Pay" (Order and pay with InPost Pay)

  2. The widget presents the screen "Twoje produkty czekają na Ciebie w aplikacji InPost Mobile" (Your products await you already in the InPost Mobile App) along with the masked telephone number assigned to the basket linked in the InPost Pay app

  3. The Customer selects "Połącz te zakupy z innym numerem telefonu"(Link these purchases with another phone number)

  4. The widget presents the popup (Czy na pewno chcesz powiązać te zakupy z numerem telefonu innym niż…" (Are you sure you want to link these purchases with a phone number other than.)

  5. The Customer confirms the linking with another phone number.

  6. The widget calls iziBindingDelete issued by the Merchant's backend, which then calls the method DELETE/v1/izi/basket/{basket_id}/binding to InPost Pay

  7. InPost Pay removes the link between the basket and the phone number, and transfers the information to the Merchant's backend regarding the correct completion of the task.

The Merchant transfers the information to the widget, which presents a screen to the customer with the association of the basket using the telephone number.

 

 

Below is a video which discusses the diagram:

 

UC.02 Binding a basket with InPost Pay using qrCode

 

Verification of the linking between the shopping cart and InPost Pay [1-6]:

  1. The Client moves to the Merchant's website

  2. The Merchant builds the store's website, while verifying whether or not the customer's basket is linked with InPost Pay, and whether or not the browser which the customer currently uses is among the trusted ones. The verification takes place through the request GET/v1/izi/basket/{basket_id}/binding to InPost Pay

  3. InPost Pay returns the information that the cart is not linked (basket_linked=false), and the browser is not trusted (browser_trusted=flase)

  4. The Merchant builds the store's website with an embedded widget with the message: "Kup z InPost Pay" (Buy with InPost Pay"

Binding using qrCode [7-30]:

  1. The customer presses the widget "Kup z InPost Pay", and then the customer sees a screen with the basket's association based on a phone number. The Customer switches to the association based on qrCode.

  2. The widget calls the method iziGetBindingData (without parameters) to download qrCode to the Merchant's backend, which, using the method POST/v1/izi/basket/{basket_id}/binding, collects qrCode from InPost Pay. In the request, the merchant transfers the data:

    1. basket_id - the basket's unique id

    2. binding_method = DEEP_LINK

    3. binding_place - the place where the basket was associated

    4. browser - an entity with the details of the browser used to make the association

  3. InPost Pay generates a qrCode/deep link, which then, through the Merchant's backend, is transferred to the widget in order to be presented to the customer.

  4. The Customer initiates the binding proces with the use of:

    1. InPost's mobile app - using which they scan the qrCode, or

    2. a deep link, which redirects to the completion of the process in the InPost Pay app

  5. Upon initiating the process, depending on whether the client has signed a contact in the InPost Pay app or not, they go to the right flow (binding the basket or onboarding to InPost Pay and binding the basket).

  6. InPost Pay binds the basket (the basket's id sent by the Merchant) with the phone number and notiifies the Merchant of binding the basket using the POST/v1/izi/basket/{basket_id}/confirmation method. The method issued by the Merchant in which InPost Pay transfers the data:

    1. basket_id - the unique identifier of the basket assigned by the merchant

    2. status - binding status [SUCCESS; REJECT]

    3. inpost_basket_id - the unique identifier of the basket assigned by InPost Pay - data used only by the widget

    4. phone_number- the phone number associated with the basket

    5. browser - an entity which informs whether or not the browser was added to the trusted ones

      1. browser_trusted - a flag which informs, whether or not the browser was added to the trusted ones

      2. browser_id - the identifier of a trusted browser, assigned by InPost Pay

    6. masked_phone_number - masked number

    7. name - customer's first name

    8. surname - the customer's surname

  7. The Merchant's backend, upon receiving the POST/v1/izi/basket/{basket_id}/confirmation which confirms the link between the basket and the success, sends in response to Inpost Pay the customer's Basket Details (the details of the basket consisting of obligatory data: summary; delivery, products, consents, and optional  promo_codes, related_products)

  8. During the basket binding process, the widget starts observing the Merchant's backend (with the use of looping, or websocket) whether or not the Merchant's backend was notified of the binding of the basket (POST/v1/izi/basket/{basket_id}/confirmation). Upon receiving the information, the widget notifies the customer of the successful binding and the completion of the payment for the products in the InPost Pay app, and saves browser_id in the local storage of the browser.

  9. After obtaining the information that the basket is now linked, the widget starts observing the Merchant's backend (with the use of looping, or websocket), to see if the order for the basket was realized. Upon receiving the information of the completion, the widget notifies the customer showing the screen with thanks for the finalization of the order.

 

 

Below is a video which discusses the diagram:

 

 

UC.03 Binding a basket with InPost Pay using a phone number

 

Verification of the linking between the shopping cart and InPost Pay [1-6]:

  1. The Client moves to the Merchant's website

  2. The Merchant builds the store's website, while verifying whether or not the customer's basket is linked with InPost Pay, and whether or not the browser which the customer currently uses is among the trusted ones. The verification takes place through the request GET/v1/izi/basket/{basket_id}/binding to InPost Pay

  3. InPost Pay returns the information that the basket is not linked (basket_linked=false), and the browser is not trusted (browser_trusted=false)

  4. The Merchant builds the store's website with an embedded widget with the message: "Kup z InPost Pay" (Buy with InPost Pay)

Binding based on the phone number [7-30]:

  1. The customer presses the widget "Kup z InPost Pay", then the customer sees a screen with the basket's association based on the phone number. The Customer enters the phone number and chooses połącz (link)

  2. The widget calls the method iziGetBindingData (with the parameters id, prefix, phoneNumber) to the Merchant's backend, which, using the method POST/v1/izi/basket/{basket_id}/binding transfers the phone number to InPost Pay., in the request, the Merchant transfers the data:

    1. basket_id - the basket's unique id

    2. binding_method = PHONE

    3. phone_number- the phone number entered by the customer

    4. binding_place - the place where the basket was associated

    5. browser - an entity consisting of the data of the browser used to make the binding

  3. InPost Pay verifies the security/spam rules of the binding for the phone number. In the case of:

    1. a positive verification, it sends response (202) to the Merchant, and sends the notifications (push) to the customer's device.

    2. a negative verification, the basket binding process is finished (InPost Pay returns an error code to the Merchant's backend).

  4. Through the push notifications, the Customer starts the InPost app, in which the customer:

    1. approves the binding of the basket

    2. signs into InPost Pay and approves the binding of the basket.

  5. InPost Pay binds the basket (the basket's id sent by the Merchant) with the phone number and notiifies the Merchant of binding the basket using the POST/v1/izi/basket/{basket_id}/confirmation method. The method issued by the Merchant in which InPost Pay transfers the data:

    1. basket_id - the unique identifier of the basket assigned by the merchant

    2. status - binding status [SUCCESS; REJECT]

    3. inpost_basket_id - the unique identifier of the basket assigned by InPost Pay - data used only by the widget

    4. phone_number- the phone number associated with the basket

    5. browser - an entity which informs whether or not the browser was added to the trusted ones

      1. browser_trusted - a flag which informs, whether or not the browser was added to the trusted ones

      2. browser_id - the identifier of a trusted browser, assigned by InPost Pay

    6. masked_phone_number - masked number

    7. name - customer's first name

    8. surname - the customer's surname

  6. The Merchant's backend, upon receiving the POST/v1/izi/basket/{basket_id}/confirmation which confirms the link between the basket and the success, sends in response to Inpost Pay the customer's Basket Details (the details of the basket consisting of obligatory data: summary; delivery, products, consents, and optional  promo_codes, related_products).

  7. During the basket binding process, the widget starts observing the Merchant's backend (with the use of looping, or websocket) whether or not the Merchant's backend was notified of the binding of the basket (POST/v1/izi/basket/{basket_id}/confirmation). Upon receiving the information, the widget notifies the customer of the successful binding and the completion of the payment for the products in the InPost Pay app, and saves browser_id in the local storage of the browser.

  8. After obtaining the information that the basket is now linked, the widget starts observing the Merchant's backend (with the use of looping, or websocket), to see if the order for the basket was realized. Upon receiving the information of the completion, the widget notifies the customer showing the screen with thanks for the finalization of the order.

 

Below is a video which discusses the diagram:

 

 

UC.04 Synchronization of the basket and the order

Basket synchronization initiated from the Merchant's store website [1-7]:

  1. When:

    1. a bound basket is being updated, or

    2. a customer creates a new basket, and is willing to pay through InPost Pay in a trusted browser.

      the Merchant should call the method PUT/v1/izi/basket/{basket_id} (the request contains the whole basket, obligatory data: summary; delivery, products, consents, and optional promo_codes, related_products) to the InPost Pay app in order to update, or create the basket.

  2. Upon receiving the request PUT/v1/izi/basket/{basket_id}, Inpost Pay updates the existing basket, or binds the basket to the phone number assigned to the trusted browser, and returns the feedback confirming the successful completion of the operation (response 200)

Basket synchronization initiated by InPost Pay [8-11]:

  1. In the InPost Pay app, the Customer will be able to update the basket in the scope of:

    1. changing the quantity of the products in the basket (quantity_event_data)

    2. adding/removing a promotion code (promo_codes_event_data)

    3. adding a suggested product to the basket (related_products_event_data)

  2. When the user performs one of the aforementioned modifications in the basket, InPost Pay, using the method POST/v1/izi/basket/{basket_id}/event, will notify the Merchant in the form of an event of the specific operation.

  3. Upon receiving the event updating the customer's basket, the Merchant should return the whole updated basket in a response (obligatory data: summary; delivery, products, consents, and optional promo_codes, related_products)

Order synchronization initiated on the website of the Merchant's store [12-13]:

  1. When:

    1. changed the status of the order, or the description of the order status presented in the store

    2. assigned a reference number to the shipment

      should call the method POST/v1/izi/order/{order_id}/event to the InPost Pay app in order to update the order's data.

  2. Upon receiving the request POST/v1/izi/order/{order_id}/event, InPost Pay updates the order, and returns the confirmation of the successful completion (response 200)

Order synchronization initiated by InPost Pay [14-15]:

  1. If the customer:

    1. paid for the order

    2. rejected the order before the payment

      notifies the Merchant of the occurrence of an event with the use of the method from POST/v1/izi/order/{order_id}/event.

  2. Upon receiving the request POST/v1/izi/order/{order_id}/event, the Merchant returns the confirmation of receiving the notification (response 200)

 

Below is a video which discusses the diagram:

 

 

UC.05 Execution of the order

Creating an order in the InPost Pay app [1-8]:

  1. The Customer moves to the basket in the InPost Pay app, completes the data required for the order (delivery form and address, invoicing data), chooses the form of payment, and initiates the order creation and the payment process by pressing the button "Kupuję i Płacę" (Buy and Pay).

  2. After the purchasing process is initiated by the customer, InPost Pay downloads the current basket from the Merchant (with the use of the method GET/v1/izi/basket/{basket_id}), and verifies, whether or not the basket's content kept at InPost Pay is compliant with the basket provided by the Merchant (verification using hash enumeration).

    1. If the basket in the InPost Pay app is invalid, a respective message is presented to the customer - koniec procesu utworzenia zamówienia na nieaktualnym koszyku (process of creating an order for an invalid basket finished).

    2. If the basket in the InPost Pay app is valid, the POST/v1/izi/order method is called to the Merchant in order to create the order (the data transferred to create the order: required: order_details, account_info, delivery, consents, optional: invoice_details)

  3. In the POST/v1/izi/order response, after the order was created correctly, the Merchant transfers the following data to InPost Pay:

    1. order_details - the order details (together with the order_id, and pos_id assigned)

    2. account_info- the client's data

    3. invoice_details - the data for the invoice

    4. delivery- the data of the order delivery method

    5. products - products list

    6. consents - the customer's defined consents

Paying for the order in the InPost Pay app [9-19]:

  1. After being notified of the creation of the order, InPost Pay assigns order_status = ORDER_PROCESSING and payment_status = UNPAID, and initiates the payment process, where, sequentially together with the stages of the payment being made by the customer, it assigns and saves the following data:

    1. payment_status = STARTED - commencing the payment by the customer in the InPost app, and generating and recording the payment's reference data

    2. payment_status = PENDING - the payment made by the customer in the InPost App and awaits to be made in the payment gate

    3. payment_status = AUTHORIZED - the payment implemented successfully in the payment gate and recording the payment's data in the order details.

  2. After the payment was completed successfully, the customer is notified in the InPost app of the successful payment for the order, InPost Pay calls the method POST/v1/izi/order/{order_id}/event in order to notify the Merchant of the payment made.

  3. The widget observes the Merchant's backend for the associated basket (with the use of looping, or websocket), to see if the order was completed. Upon being notified of the completion, the widget shows the customer the screen with the thank you message for the finalization of the order.

 

Below is a video which discusses the diagram: