[ENG] InPost Pay - Magento

Open

Introduction

This manual presents the process of installing and configuring the plugin which makes it possible to deploy InPost Pay in the Magento store.

Plugin: 1.0.8 (05.09.2024)

Open

*The plugin is currently still under development, new versions of the plugin will appear, follow changelog and install new versions as soon as they're released.

Changelog

Na tej stronie

System Requirements

The InPost_InPostPay plugin requires meeting the following server criteria to operate correctly:

·       Magento 2 Community Edition (Open Source) version > =2.4.6

·       PHP version > =8.2

·       Composer version > =2.2

and any requirements imposed by Adobe for the Magento version installed:
System requirements | Adobe Commerce

Optional features:

• Default- basket updates initiated on the customer's side in the browser are sent synchronically to the InPost Pay API server.
  The plugin makes it possible to configure the sending of these data in an asynchronous manner with the use of the queue mechanism based on MySQL embedded in Magento. One requirement is to configure CRON correctly to activate the consumer process. When configuring the activation of the consumer process, follow the documentation (Manage message queues | Adobe Commerce ) or use a Supervisord tool (https://supervisord.readthedocs.io/en/latest/ )

Configuration

This documentation section contains the configuration manual along with descriptions of the particular components of the InPost Pay plugin dedicated to the Magento 2 platform.

Mapping the Delivery Methods

Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Mapping Delivery Methods

Description of configurable fields:

Configuration view:

Open

General Settings

Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia Ogólne

Description of configurable fields:

Configuration view:

Sandbox

Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Sandbox

Description of configurable fields:

Configuration view:

Authorization Settings

Configuration path:
Store->Configuration-> Sales->Payment Methods->InPost Pay-> Authorization Settings

Description of configurable fields:

Configuration view:

Debugging Settings

Configuration path:
Store->Configuration-> Sales->Payment Methods->InPost Pay-> Debugging Settings

Description of configurable fields:

Configuration view:

IZI API Settings

Configuration path:
Store->Configuration-> Sales->Payment Methods->InPost Pay-> IZI API Settings

Description of configurable fields:

Configuration view:

Mapping the Consents (changes since version 1.0.8)

Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Terms and Conditions Mapping Settings

Description of configurable fields:

Configuration view:

Configuration Example:

a) Basic configuration:

The appearance of the app:

Explanation:
In the base case, there is no additional links attached under the master consent. They are simply two separate consents of which one is required, the other one is optional. The link to the consents is placed at the end in the brackets as the "(link)".

b) Configuration with the embedded consents

The appearance of the app:

Explanation:
In this case, we are dealing with a consent containing additional links to different terms and conditions in its content. To achieve such a result, not only the mapping of the consents must be configured correctly in the InPost Pay plugin, but also the consents must have the correct title in the native Magento configuration: Store-> Terms and Conditions:

The screenshot above demonstrates the master consent entitled:
"I confirm that I've read the content of #1 and #6, and I accept their provisions."

Where #1 and #6 correspond to the identifiers of the consents. In this case, #1 refers to itself, and #6 to the "Privacy Policy" consent.

In the configuration of the plugins and the mapping of the consents, the setting of the "Privacy Policy" consent is visible as ADDITIONAL_LINK.

and the setting of its master consent

And the final addition of the text which will replace "the (link)", making it possible to ensure the proper grammatical form, in this case "Polityki Prywatności" and "Regulaminu"

With the configuration above, the InPost Pay App will not show the ADDITIONAL_LINK consent separately, but it will be attached under #6 as a link in the content of the master consent, and, being the master consent, it also has its own #1 identifier and the text of the "Terms and Conditions" link, the final result  presented in the app will be as follows:

"I confirm that I've read the content of the terms and conditions and the privacy policy, and I accept their provisions."

Where the link to the full content of the consent is hidden under the text of the "Terms and Conditions" and the "Privacy Policy".

Display Settings

Configuration path:
Store → Configuration → Sales → Payment Methods → InPost Pay → Display Settings

Description of configurable fields:

Configuration view:

Button Layout Settings

Configuration path:
Store → Configuration → Sales → Payment Methods → InPost Pay → Button layout settings

Description of configurable fields:

Configuration view:

Cache Settings

The InPost_InPostPay module uses the native Cache mechanism, to optimize the integration process. The cache memory contains the public keys collected to verify the signature at the authorization of inbound requests from InPost to a Merchant's API, and the consent configuration.

It is recommended to activate the handling of these cache memory settings. To do this, unfold the side panel in the Administration Panel and the System item, and then move to Memory Management.

System->Cache Management

The next step is checking the following options:

and choosing the activation items checked from the unfolding option list:

Module Installation - Additional Information

In this section of the documentation, there is an additional information for customers, who want to push the InPost Pay button in the checkout page, and have a modified checkout procedure.

The component with the InPost Pay button has been added on the checkout page as the next step (apart from delivery and payment). It has been added before the steps above.

Such a change required re-configurating the dependencies in the progress bar component:

If the customer has a modified checkout page (an additional step on the checkout page e.g.. logging/registration, modified dependencies on the progress bar), in this scope the checkout page must be adjusted and the above changes taken into consideration.

Long Polling Settings

Configuration path:
Store → Configuration → Sales → Payment Methods → InPost Pay → Polling Settings

Description of configurable fields:

Configuration view:

Omnibus Settings (changes since version 1.0.8)

Configuration path:
Store → Configuration → Sales → Payment Methods → InPost Pay → Omnibus Promo Settings

Description of configurable fields:

Configuration view:

Explanation of how the configuration works:

By default, the lowest prices from the previous 30 days are not sent through the InPost Pay plugin to the Mobile Application API of the customers, even if the products in the customer's baskets have a specified value in this attribute. For the prices to be transferred, the product in a customer's Magento basket must be subjected to the basket rule, which is designated in the configuration of the InPost Pay plugin as "Omnibusowa type" in the form of the above described multiple choice list. The rule itself does not have to include a discount or reduce the price. It is sufficient that it is configured so that it is activated, and the criteria of both the basket and its content are fulfilled by the customer's basket, which must have the lowest price from the previous 30 days visible in the Mobile App.

Restrictions Settings (changes since version 1.0.8)

Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay-> Restriction Settings

Description of configurable fields:

Configuration view:

User Manual

This documentation section contains instructions concerning placing an order in the online store by means of the InPost Pay plugin and the Mobile app.

Purchase on the Merchant's website by means of InPost Pay

Requirements

• service with the InPost Pay module installed

• InPost Mobile app

Description of action

To submit an order, proceed to the website to the product's page where the button "Utwórz koszyk z InPostPay" is present (If products are already in the basket then we can also submit the order by using the button InPostPay, which is also present in the mini basket and  on the basket's page).

.

Click the button provided to add the product to the basket and start the baskets coupling process. After clicking and adding the product to the basket, a popup will appear where we choose the baskets coupling method. We can do this by:

1. specifying a phone number
   
   

    

After entering the phone number and clicking the button "Połącz", the popup content is changed

and the process of binding the baskets begins in the InPost Mobile app. The app on the mobile device displays the message that your basket awaits you in the app. In this situation, we can:

• link the basket by clicking OK on the basket in the app

• we can return to the website and continue the purchasing process within the store by clicking the button "Kontynuuj zakupy na stronie sklepu".

2. scanning a QR code

After scanning down a QR code in the InPost Mobile app, the baskets are coupled up and we go to a basket.

After combining the baskets (by using the above methods) the popup disappears within the website and the button changes its appearance and notifies that the baskets are now coupled.

At this stage, we have the option of ordering using the app and also completing the order on the website. The basket in the website is now combined with the basket in the app, and any actions performed in the shopping basket (adding a product, removing a product, increasing the quantity of products) will be synchronized between the baskets (within the website, inquires about the status are handled and the synchronization  of the basket data may proceed after maximum 10 seconds). One operation which is also synchronised between the baskets is the removal of a basket. If we remove a basket in the InPost Mobile app, the basket binding is removed but the basket in the website remains unchanged. Clicking the "Utwórz koszyk InPost Pay" again links the basket this time without specifying any phone number or scanning any QR code, since the data have already been saved in the website and the app. When processing an order in the app, it is possible to enter rebate codes that are available in the website.

When selecting the purchasing process in the app - upon placing an order in the app, the website directs us to the Thank You page

When processing an order on the website, upon placing the order in the app, a message appears that the basket no longer exists or has been removed.

Configuration of products covered by restrictions and not covered by InPost Pay sales

Together with the InPost Pay plugin, a module is also delivered that makes it possible to manage what products cannot be handled by the InPost Pay mobile app for business or logistical reasons.

Configuration:

In the Administration Panel, from the side Menu, select the section Stores, and then InPost Restrictions-> Restriction Rules from the drop-down list.

A table will be displayed with a list of currently configured rules which make it impossible to sale the selected products through the InPost Pay mobile application.

In order to exclude the selected products from handling through InPost Pay, create a new rule with the button in the top right corner, then complete the main section in the form, specifying:

• the rule's name, which is intended to facilitate identifying what the rule applies to. This name is not displayed to the customers.

• set the rule's status to on or off

• set the website the rule relates to

• set which delivery method is covered by the rule (Courier, APM or both methods at the same time)

Then, display the section of the conditions to be met by the excluded products and, using the conditions configuration wizard typical for Magento (similar to the one from the Catalogue Promotional Rules) specify what characteristics exclude a product from sale through InPost Pay.

The last step is saving the rule with the button on the right side at the top. The saving process may take from a few to twenty seconds depending on how many websites, stores are configured in Magento, how many products there are, which results from the structure of the list of products covered by the restrictions.

The list of products covered by the restrictions can be viewed in the tab Store-> InPost Restrictions-> Restricted products

Helpful additional information:

The exclusions list refreshing process may be automated and controlled from the configuration level:
Store->Config->Sales->Payments->InPost Pay->Restrictions Settings
By default, refreshing is activated four times a day at 1:30 am, 7:30 am, 1:30 pm, and 7:30 pm, but when necessary, these hours can be set in accordance with one's preferences, bearing in mind however that, depending on the large number of products offered and the rules configured, the time necessary to process the refreshing of the exclusions list may be longer, and that the appearance or disappearance of the exclusion of a product clears the FPC memory of this product's page, thus it is not recommended to set this process too often, unless this is necessary.

The list of attributes for selecting restriction conditions contains only such characteristics of products that have a specified availability for the catalogue rebate filters. This is the configuration of each product attribute. This setting may be changed in the tab: Store-> Attributes-> Product, by editing an attribute, and the configuration mentioned is in the section Storefront Properties.

The value YES results in that a given attribute will be used as an exclusion filter.

After re-entering the edition form or creating a new rule, the attribute appears on the list:

It should be remembered that when configuring the exclusion conditions, not only the value is modifiable, but also a combination of conditions, and the comparison operator.

In this way, a variety of conditions could be configured which meet business requirements, as for instance:

• X category products or products the price of which is greater than Y.

Returning Manual

To make a return, we need to have the order processed (paid) through InPost Pay.

Then, enter the Magento administration panel and our order (Sales → Orders → Order View), and click the Credit Memo button:

In the next step, the Credit Memo view will open. Click the Refund Offline button - after this action the return is submitted in Magento, and the request sent to InPost, in order to refund the funds from InPost Pay.

After creating the Creditmemo, a comment should be added to it.
If the return is created correctly in InPost, a description will be provided in a form similar to the one below

Example from a specific return:

If any error takes place, then the following notification appears in the comment

The accurate information about the error is in the logs on the server, eg.:
var/log/inpost-pay/2024-04-11.log

Technical Documentation - Backend

This documentation section contains technical information regarding communication with the InPost API, the frontend Widget, and the debugging of the processes that take place in the InPost Pay plugin.

Signature Verification

Each request coming from InPost to the Magento API addresses of the InPost Pay plugin are verified for the signature to ensure security. A detailed description of the signature verification algorithm can be found in InPost's public documentation: Signature Verification.

The following interface is used to verify the signature:
\InPost\InPostPay\Api\Validator\SignatureValidatorInterface

The validate method expects the following text type parameters:

The first four of those are available from the headers of the requests sent from InPost to Magento. The last one is simply the whole content of a request.

Signature verification process:

1. Comparing the hash from a request with the value collected from the InPost API which is a public key.

   1. For this purpose, first the authentication takes place using the access data from the configuration process in order to download a token.

   2. Then, the token is used as a Bearer Token In the request for the public key data from the InPostu API.

   3. The responses with InPost's data together with the public keys according to the requirement of the documentation is stored in Magento's cache under the key which is the version sent in the header of the request being verified.

2. Generating the signature based on the algorithm described in InPost's documentation and comparing it with the decoded value of the signature from the header of the request being currently verified.

   1. For this purpose, it is necessary to calculate the signature on the basis of the data:

      1. the content of the request (SHA256 and then base64)

      2. the external ID of the store available in the cache mentioned in item 1.c

      3. the version of the request

      4. timestamp from the request
         Encode the data above separated with commas in Base64

   2. Prepare an asymmetric public key on the basis of the content of the key from the data in item 1.c

   3. Compare the expected signature using openssl_verify from item 2.a, against the signature value from the request currently being verified using the prepared public key from item 2.b

3. The last step of the signature verification process is comparing the time of the request sent in the header in UTC against the current time, taking into account the maximum 240 seconds life time of this request.

    

Connector API

The interface used to handle inquiries sent from Magento to the InPost API.

The implementation uses \GuzzleHttp\Client in order to implement POST/GET/PUT requests etc. directed to the relevant URL address consisting of the base URL of the given API, and the URI of the given endpoint. Parameters and also headings are added to the request.

The headings, parameters, the base URL, and the endpoint URI, and the kind of the GET/POST/PUT method etc..are determined by the request object transferred to the sendRequest connector method, which must implement the request interface which contains the information necessary to send it:

(List of methods and implementations: Interface of Requests for InPost API)

The sendRequest method always returns an array, if the answer is JSON, it will be unlocked and returned back in its original form, if not and no new array is created as a result of unlocking, an array with the result key and that value is returned.

Depending on the configuration of: Debugging Settings, the whole request, or only exceptions with errors are logged up.

Interface of requests for InPost API

Each request, which is to be used by the Connector API, needs to implement this interface:

As part of the interface it is required to implement the methods of the given request:
getApiUrl

getMethod

getContentType

getBearerToken

getParams

setParams

The current list of requests:

Handling requests for InPost API and formatting the responses

To collect data from InPost's API, services are used, the purpose of which is to create the objects of requests which implement the interface and provide them with suitable parameters

(List of methods and implementations: Interface of Requests for InPost API)

then, to send them through the Connector API

, and to assign the final formatting of the response. The form of the response returned depends on the particular implementation of the handling of a given request, the standard is to add the handle method which takes an array as an argument and returns the object of the response to the given request (DataObject) created and supplied with data.

The current list of services:

The current list of the responses to requests:

The relation between the official Smartmage_Inpost plugin and InPost_InPostPay

The InPost_InPostPay plugin does not require InPost's official plugin for handling deliveries through the Paczkomat 24/7 locker devices or the InPost Courier service, but they can function together without any problems.

Scenario #1: Both plugins are installed on a single Magento 2 installation

The Smartmage_Inpost plugin ads a column with the selected Paczkomat 24/7 Automatic Parcel Locker Device (code) stored to the native array with orders and baskets in the database. These are the columns:

Within the ordering process, the Smartmage_Inpost plugin first saves the device code selected by the customer to the basket's array, and then, when placing the order, Event Observer is activated:

The value selected by the customer is visible in the Administration Panel in the order view on the right side under the delivery method chosen:

In a similar manner, the InPost_InPostPay plugin observes in the same event the process of saving the order, and transfers the value of the code of the Paczkomat 24/7 Parcel Locker device chosen from the basket to the order, if the following conditions are fulfilled:

• payment method: inpost_pay

• quote.inpost_pay_locker_id is complete

• the delivery method is the one which is mapped to Paczkomat 24/7 in the InPost Pay mapping configuration Mapping the Delivery Methods
  
  

In the Administration Panel, in the order view, the value of the chosen device's code is displayed in this scenario #1 by the initiative of the InPost_InPostPay plugin since the Smartmage_Inpost plugin is responsible for this in this case.

Scenario #2: Only the InPost_InPostPay plugin is installed in Magento 2

A block with an information identical as the one in scenario #1 also generates the InPost_InPostPay module when the following preconditions are met:

• payment method: inpost_pay

• The Smartmage_Inpost module is not activated

• The order is not virtual

Debugging

The InPost_InPostPay plugin has its own Log Handler, which has its own logging levels handling process based on the configuration:
Debugging Settings

Regardless of the system settings, all the levels are subject to logging, from the configured one to the most critical one:

When processing the data, processing the queries to API, handling errors etc., the logger injected by di.xml is used in many places, e.g.:

In the wizard of this object, the logger is:

The logging level is specified by the method called on the $logger object:

Storing the logs:

The place of logs storage is handled by:

where the path to the .log file is built in the wizard the form of which is based on the current date, for instance:

Log format:

Each entry in the logs for which this Handler was used will be preceded by a unique id generated within the process, to facilitate tracking and debugging when there are numerous requests and processes activated at the same time.

Additionally, to ensure helpful data on the one hand, and, on the other hand, to avoid logging explicitly certain information, some logs that may include sensitive data are encoded in base64.

An example of such logs are data sent and collected to and from the InPost API:

Example logs:

Frontend controllers

The controllers used for communicating between the frontend Widget and the backend Magento.

REST API Magento implementations

DELETE /v1/izi/basket/:basketId/binding

A controller intended to delete a basket by a user in the InPost Pay App.

Request Type – DELETE

Endpoint URL: /v1/izi/basket/:basketId/binding

Response – none. 200 – means, confirmed receipt of the information about the removal of the basket.

Possible errors:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

POST /v1/izi/basket/:basketId/confirmation

An endpoint used to verify the binding of a basket in the InPostPay app.

Request Type – POST

Endpoint URL: /v1/izi/basket/:basketId/confirmation

Response – Returned object type \InPost\InPostPay\Api\Data\Merchant\BasketInterface
InPost Pay Basket

Sample request:

Response 200

MPossible errors:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

GET /v1/izi/basket/:basketId

An endpoint intended to collect a basket's data.

Request Type – GET

Endpoint URL: /v1/izi/basket/:basketId

Response – Zwracany jest obiekt typu \InPost\InPostPay\Api\Data\Merchant\BasketInterface
InPost Pay Basket

Response 200

Possible errors:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

POST /v1/izi/basket/:basketId/event

An endpoint used to update a basket in Magento.

Request Type – POST

Endpoint URL: /v1/izi/basket/:basketId/event

Response – Zwracany jest obiekt typu \InPost\InPostPay\Api\Data\Merchant\BasketInterface
InPost Pay Basket

Sample request:

Response 200:

Possible errors:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

POST /v1/izi/order

An endpoint used to create an order in Magento.

Request Type – POST

Endpoint URL: /v1/izi/order

Response – Object type \InPost\InPostPay\Api\Data\Merchant\OrderInterface is returned
InPostOrder

Sample request:

Response 200:

Possible errors:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

\InPost\InPostPay\Exception\OrderNotCreateException 409

GET /v1/izi/order/:orderId

An endpoint intended to collect an order's data.

Request Type – GET

URL endpoint: /v1/izi/order/: orderId

Response – Object type \InPost\InPostPay\Api\Data\Merchant\OrderInterface is returned
InPostOrder

Response 200

Possible errors:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\OrderNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

POST /v1/izi/order/:orderId/event

An endpoint used to update an order in Magento.

Request Type – POST

URL endpoint: /v1/izi/order/: orderId/event

Response – Object type \InPost\InPostPay\Api\Data\Merchant\OrderUpdateInterface is returned

Sample request:

Response 200:

Possible errors:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\OrderNotFoundException 404

InPost\InPostPay\Exception\OrderNotUpdateException 409

InPost\InPostPay\Exception\InPostPayInternalException 500

The Process of Creating an Order

The creation of an order is initiated by InPost through the request: POST /v1/izi/order

Verifying an order's data for correctness

Before commencing any modification of a basket's session to transform it into an order, first the data sent from InPost is verified. This is handled by the list of validators, which are specified in the file:

in the form of:

The above injected validators are responsible, among other things, for:

• verifying if the final total price for the products and shipment taking any rebates into account is right

• is the payment form chosen in the Mobile app is compliant with the configuration: IZI API Settings

• is the delivery form chosen through the InPost Pay app available for this basket session in Magento

• are the consents required accepted

• the correctness of settlement data

• are the products available

If the Merchant, within the validation of an order, needs any changes, they can be easily made using plugins or adding further validators dedicated to this Merchant.

Creating an order

The data sent from InPost are processed in stages similarly to the native checkout operation.
The stages are specified in the file:

in the form of:

The orderProcessingSteps stages supply the basket session with the following data:

• assigning a customer, if the basket belongs to a guest, and the email address is included among those registered

• supplementing the data of the settlement address

• supplementing the data of the delivery address

• specifying the delivery method

• specifying the payment method

• reloading the basket session to convert the total amount

If the Merchant, as part of creating an order, needs any changes within the process, the steps can be easily modified using plugins, or adding another stage using the module dedicated to this specific Merchant case.

Processing a newly created order

After creating an order, it is necessary to perform several steps specified in:

in the form of:

The orderPostProcessingSteps for processing the activities after creating:

• initiating a record in the database for the order from InPost Pay

• saving the chosen collection site (if this method was chosen)

• saving the selected delivery options (Parcel on Weekend, Cash on Delivery etc.)

• saving the accepted consents

If the Merchant, upon creating an order, needs to make some additional steps, further processing steps, dedicated to the given Merchant, can be easily injected for the order created.

Objects returned through the Magento API

When communicating with Rest API, Magento returns the following objects:

Basket: InPost Pay Basket
Order: InPost Pay order (InPostOrder)

InPost Pay Basket

Interface: \InPost\InPostPay\Api\Data\Merchant\BasketInterface
Implementation: \InPost\InPostPay\Model\Data\Merchant\Basket

Description:

In the code, the InPost Pay Basket is referred to as the basket to distinguish from a quote or a cart.
The object imitates a Magent basket session so that it meets the requirements of communicating with the InPost Pay API.

The Basket object is supplied with data from the basket session using the DataTransfer class and the transfer method, which transfers and processes the data from the Magento basket session into the Basket object:

InPostOrder

Interface: \InPost\InPostPay\Api\Data\Merchant\OrderInterface
Implementation: \InPost\InPostPay\Model\Data\Merchant\Order

Description:

The object imitates a Magento order so that it meets the requirements of communicating with the InPost Pay API.

The InPost order object is supplied with data from the Magento order using the DataTransfer class and the transfer method, which transfers and processes the data into the object:

Merchant's customized modifications

The InPost_InPostPay module has been written so that it is possibly easy to modify for the individual requirements of different Merchants.

1. The Product Data sent to the InPost Pay app

To modify any product data, handle the transfer of attributes differently, changes in the stocks etc., add the definition of the following class plugin in the module dedicated to the given Merchant in di.xml:

and prepare the Plugin class which implements the afterTransfer method or possibly aroundTransfer by adding any customized business logic.

Attention: Any product data generated using this mechanism relate both to the Basket and the Order visible in the InPostPay Mobile app.

By analogy to the product data, the data of the delivery, consents, associated products, rebate codes applied, and the summary of the order could be modified in the same way using the plugins of the classes:

bearing in mind however that the data presented in the InPostPay Mobile app must match those presented in the Magento basket, particularly the prices, taxes, and delivery costs.

2. Delivery date

Integration with the InPost Pay API requires providing the delivery date both in the basket and in the order's data. By default, the InPost_InPostPay module, due to its universal nature, has no calculation of this date implemented based on the mapped delivery methods, different warehouse stocks, delays etc., owing to the lack of the information necessary to calculate such a date. In the Delivery Methods Mapping configuration, there is a required field, based on which this date is calculated regardless of the delivery method selected. In order to calculate the date based on a more customized business logic, the definition of the plugin class in di.xml must be added:

and the Plugin class which implements the afterCalculateDeliveryDate method or possibly the aroundCalculateDeliveryDate method must be prepared by adding the customized business logic.

3. Order Placing Process modifications

The process of creating an order has been described in detail in Chapter the Process of Creating an Order. In order to make changes in the process of creating an order or initially validating the data transmitted from InPost, it is enough to use the di.xml file to inject additional steps, or by defining the plugin for the order validator classes and/or processor classes:

Restrictions Module

In order to enable excluding particular products from the handling through InPost Pay, a separate dedicated InPost_Restrictions module has been created. This module is required by the main InPost_InPostPay plugin. The configuration of the restrictions is described in the section: Configuration of Products Covered by Restrictions and not Covered by InPost Pay Sales.

Within the InPost_Restrictions module, two arrays in the database have been created:

inpost_restrictions_rule - contains the definitions of the product excluding rules
inpost_restrictions_rule_product - contains the products which meet the criteria of the rules

After being saved automatically, the Restriction Rules generate a list of products and save it in the database. It is necessary to have in mind that the native mechanism for validating the set of rules works so that all the products for all the stores in a website configured go through the configured filter, and, based on that, a list of the IDs of the products which meet the criteria is built. This could mean that, in the case of a few dozen thousand products for a Magento instance with many stores for the given website, the process of saving a rule may be extended to from a few to twenty/several dozen seconds. This is assumed to be a one-time process, and, because of the maximum simplification in the installation and configuration of the plugin, it is performed synchronically, to prevent the necessity to require the Merchant to add and manage CRON processes.*

On the product page of these products the IDs of which are on the list, the widget for binding a basket will not be loaded. If, despite this, the product is added to a basket, upon binding it with the application, the app should display a warning message, and no delivery methods will be available to prevent the completion of such an order in the app.

Information related to optimization:

To minimize any delays in loading a page, when checking whether or not the product is covered by the restrictions, Magento's cache is used.

Within the native management of the cache, make sure that it is activated for this item.

The restriction cache and the FPC which uses the tags of products covered by the restrictions are automatically cleaned for the rule being saved and its products. Even if the cache is turned off or not warm, the product collection is downloaded directly from a single array in the database from indexed columns to minimize the delays in loading the pages resulting from determining whether or not the widget is to be displayed or not.

This process occurs in the observer:

Removing HTML and special characters from text attributes

Owing to the restrictions and the security rules on the side of the InPost Pay API servers, the data sent in the requests must not have any HTML code or certain special characters.
In the case of any forbidden special character, for instance in the description of a product in a basket synchronized with the customer's app in their phone, the server removes some data from the request, resulting in a 403 code response -which prevents communication.

In connection with the fact that Magento implements the page builder for description type attributes, and makes a broad range of manipulation possible in the description in the form of HTML, a mechanism for cleaning text attributes has been created.

The class responsible for cleaning the text from HTML and special characters is:
\InPost\InPostPay\Model\Utils\StringUtils

The cleanUpString method performs a number of text replacements based on regular expressions in order to remove any markers, styles, tags, embedded images etc. In addition, this class uses an additional list of special characters, which are subject to the removal from the text, those include:
\InPost\InPostPay\Provider\Description\ForbiddenSignsAndPhrases

All the values from the array $forbiddenSignsAndPhrases in the class above are combined into a regular expression which then cleanses the attribute text.

Limiting the deliveries only to PL

Limiting the deliveries only to PL depends on the mapped delivery methods for InPostPay, and takes place through verifying the current address in a basket, if the basket has no address assigned then the country in the delivery code is set automatically to Poland, which makes it possible to place the order in the app.

If the user is logged in and doesn't have the delivery address entered then, when checking the delivery methods available, the customer's default address is taken into account. If the customer does not have a default address then the country of delivery is automatically set to Poland.

This happens in the class

Bundle Products

We send product_id_item_id to the InPostPay app as the product_id for the bundle products. Example a bundle product within a store has product_id 45, and in the quote_item array the product added has id 10, then the InPostPay app receives product_id 45_10, this is necessary to distinguish different configurations of the same bundle product when updating the product from the InPostPay app to Magento.
Additionally, the options selected for a bundle product are sent as an attribute of the bundle product

Generating Return Signature

In order to create a return (transaction refund) in InPost, it is required to generate a signature, and add it to the request to be sent.

It is an additional signature of a message required for the verification of the request. Calculated by combining the values of several fields. A detailed description of how to build the signature can be found in InPost's public documentation: Return Signature.

The following service is used to generate signatures:
\InPost\InPostPay\Service\Refund\SignatureGenerator

which, as a parameter, assumes the interface:

\InPost\InPostPay\Api\Data\Merchant\RefundInterface

Based on the data transferred:

• X-Command-ID - required field

• transaction_id - required field

• external_refund_id - optional field

• refund_amount - optional field - if the field is empty, the full amount will be returned

• additional_business_data - optional field

• merchantSecret - additional, required field, which is downloaded from the configuration
  Stores-> Configuration-> Sales-> Payment Methods-> InPost Pay -> Authorization settings

a signature is generated, which is attached to the request for refunding the funds for the transaction specified.

The default hashing algorithm is the algorithm: sha512, but a different one can also be used.