InPost Pay - Magento (Widget 2.0) [ENG]
Introduction
This instruction presents the process of installing and configuring a plugin that enables the implementation of InPost Pay in a Magento store with Widget 2.0 support.
Plugin 2.4.2 (16.12.2025 r.)
Magento Community Edition
Commerce Edition
Plugin for Hyva Theme and Hyva Checkout
Important:
Before installation, make sure that you have the Hyva theme installed. The module only works in an environment with the appropriate version of this theme.
Changelog
On this side:
- 1 Introduction
- 1.1 Changelog
- 2 System Requirements
- 3 Configuration for Widget 2.0
- 3.1 Delivery Method Mapping
- 3.2 General Settings
- 3.3 Sandbox
- 3.4 Authorization Settings
- 3.5 Debugging Settings
- 3.6 IZI API Settings
- 3.7 Consent mapping
- 3.8 Display Settings
- 3.9 Button layout settings
- 3.10 Cache Settings
- 3.11 Module installation - additional information
- 3.12 Long Polling Settings
- 3.13 Restrictions Settings
- 3.14 Omnibus settings
- 3.15 Available In-App Promotions
- 3.16 Sharing InPost Pay logs
- 3.17 Analytics Settings
- 3.18 Digital Products Sale Settings
- 3.19 Order Errors Handling Settings
- 3.20 Bestseller Products Settings
- 4 User guide
- 4.1 Bestseller Products configuration
- 4.2 Configuration of restricted products and products not sellable via InPost Pay
- 4.3 Instructions for creating a refund
- 4.4 Purchase of Digital Products
- 4.5 Coupon available only in the InPost Pay Mobile Application configuration
- 4.6 Email Addresses of InPost Pay orders
- 4.7 Instructions for Adding Recommended Products
- 5 Technical Documentation - backend
- 5.1 Signature Verification
- 5.2 Connector API
- 5.3 Request Interface for requests to InPost API
- 5.4 Handling of requests to InPost API and formatting responses
- 5.5 Relationship between the official Smartmage_Inpost plugin and InPost_InPostPay
- 5.6 Debugging
- 5.7 Frontend controllers 2.0
- 5.8 Magento REST API implementations
- 5.9 Order Creation Process
- 5.10 Objects returned by the Magento API
- 5.10.1 InPost Pay Basket (Basket)
- 5.10.2 InPost Pay order (InPostOrder)
- 5.11 Merchant-specific custom modifications
- 5.12 Restrictions Module
- 5.13 Clearing HTML and special characters from text attributes
- 5.14 Restriction of deliveries to PL only
- 5.15 Bundle products
- 5.16 Signature generation for refunds
- 5.17 External initiation of InPost Pay basket - Hot Products
- 5.18 Changes to Widget v 2.0
- 5.19 GraphQL (2.0)
- 5.20 FE documentation for implementation on PWA
System Requirements
The following server criteria must be met in order for the InPost_InPostPay plugin to function properly:
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 installed version of Magento:https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/system-requirements.html?lang=en, including the enabled MSI Inventory Management module.
Optional functionalities:
By default - basket updates initiated on the customer side in the browser are sent synchronously to the InPost Pay API server.
The plugin allows you to configure the dispatch of this data asynchronously using Magento's built-in MySQL-based queuing mechanism. In order to run the consumer process, CRON must be correctly configured. When configuring the running of the consumer process, follow the documentation (https://experienceleague.adobe.com/docs/commerce-operations/configuration-guide/message-queues/manage-message-queues.html ) or use tools like Supervisord (https://supervisord.readthedocs.io/en/latest/ )
Configuration for Widget 2.0
This section of the documentation provides configuration instructions with descriptions of the various components of the InPost Pay plugin dedicated to the Magento 2 platform.
Delivery Method Mapping
In order to ensure transparency and consistency of the customer experience, delivery costs must be identical in the online store interface and in the app. It is necessary to configure both systems to present users with the same delivery fee values for the respective methods.
Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Delivery Method Mapping
Description of configurable fields:
Standard Pickup Point Delivery | Configuration that allows you to assign a delivery method that corresponds to the standard shipping option via InPost's 24/7 APM in the InPost Pay Mobile app. |
Other Standard Pickup Point Delivery | If the drop-down field above doesn't have a shipping method that matches the shipping method you want to map, for example, due to the Owebia_AdvancedShipping plugin, you can add the mapping directly by entering the full shipping method code, e.g., for Owebia: owsh1_pickuppl. The method mapped in this field will override the mapping in the drop-down list above. |
Pickup Point Weekend Delivery | Configuration that allows you to assign a delivery method that corresponds to the weekend shipping option via InPost's 24/7 APM in the InPost Pay Mobile app. Note: In the Mobile app, the mapped delivery method shows up as a checkbox with an additional fee that is the calculated difference between this assigned delivery method and the standard option. |
Other Pickup Point Weekend Delivery | If the drop-down field above doesn't have a shipping method that matches the shipping method you want to map, for example, due to the Owebia_AdvancedShipping plugin, you can add the mapping directly by entering the full shipping method code, e.g., for Owebia: owsh1_pickuppl. The method mapped in this field will override the mapping in the drop-down list above. |
Pickup Point Delivery - Cash on Delivery | Configuration that allows you to assign a delivery method that corresponds to the shipping option with payment on delivery via InPost's 24/7 APM in the InPost Pay Mobile app. Note: In the Mobile app, the mapped delivery method shows up as a payment method (not delivery) with an additional fee representing the calculated difference between this assigned delivery method and the standard option. |
Other Pickup Point Delivery - Cash on Delivery | If the drop-down field above doesn't have a shipping method that matches the shipping method you want to map, for example, due to the Owebia_AdvancedShipping plugin, you can add the mapping directly by entering the full shipping method code, e.g., for Owebia: owsh1_pickuppl. The method mapped in this field will override the mapping in the drop-down list above. |
Pickup Point Weekend Delivery - Cash on Delivery | Configuration that allows you to assign a delivery method that corresponds to the shipping option with payment on delivery on the weekend via InPost's 24/7 APM in the InPost Pay Mobile app. Note: In the Mobile app, the mapped delivery method shows up as a payment method (not delivery) with an additional fee representing the calculated difference between this assigned delivery method and the standard option. To order goods in this form, the customer must select Standard 24/7 APM delivery, check the Weekend Parcel option and select cash on delivery. For example: Configuring this delivery option with prices that are not compatible will result in the rejection of the order placed by the customer through the mobile application due to the incorrect total amount. |
Other Pickup Point Weekend Delivery - Cash on Delivery | If the drop-down field above doesn't have a shipping method that matches the shipping method you want to map, for example, due to the Owebia_AdvancedShipping plugin, you can add the mapping directly by entering the full shipping method code, e.g., for Owebia: owsh1_pickuppl. The method mapped in this field will override the mapping in the drop-down list above. |
Standard Courier Delivery | Configuration that allows you to assign a delivery method that corresponds to InPost Courier in the InPost Pay Mobile app. |
Other Standard Courier Delivery | If the drop-down field above doesn't have a shipping method that matches the shipping method you want to map, for example, due to the Owebia_AdvancedShipping plugin, you can add the mapping directly by entering the full shipping method code, e.g., for Owebia: owsh1_pickuppl. The method mapped in this field will override the mapping in the drop-down list above. |
Weekend Courier Delivery | Configuration that allows you to assign a delivery method that corresponds to the weekend delivery shipping option via InPost Courier in the InPost Pay Mobile app. Note: In the Mobile app, the mapped delivery method shows up as a checkbox with an additional fee that is the calculated difference between this assigned delivery method and the standard option. |
Other Weekend Courier Delivery | If the drop-down field above doesn't have a shipping method that matches the shipping method you want to map, for example, due to the Owebia_AdvancedShipping plugin, you can add the mapping directly by entering the full shipping method code, e.g., for Owebia: owsh1_pickuppl. The method mapped in this field will override the mapping in the drop-down list above. |
Cash on Delivery Courier | Configuration that allows you to assign a delivery method that corresponds to the shipping option with cash on delivery via InPost Courier in the InPost Pay Mobile app. Note: In the Mobile app, the mapped delivery method shows up as a payment method (not delivery) with an additional fee representing the calculated difference between this assigned delivery method and the standard option. |
Other Cash on Delivery Courier | If the drop-down field above doesn't have a shipping method that matches the shipping method you want to map, for example, due to the Owebia_AdvancedShipping plugin, you can add the mapping directly by entering the full shipping method code, e.g., for Owebia: owsh1_pickuppl. The method mapped in this field will override the mapping in the drop-down list above. |
Cash on Delivery Courier | Configuration that allows you to assign a delivery method corresponding to the shipping option with cash on delivery on the weekend via InPost Courier in the InPost Pay mobile app. Note: In the Mobile app, the mapped delivery method shows up as a payment method (not delivery) with an additional fee representing the calculated difference between this assigned delivery method and the standard option. To order goods in this form, the customer must select Standard InPost Courier, check the Weekend Parcel option and choose cash on delivery. For example: Configuring this delivery option with prices that are not compatible will result in the rejection of the order placed by the customer through the mobile application due to the incorrect total amount. |
Other Cash on Delivery Courier - Weekend Delivery | If the drop-down field above doesn't have a shipping method that matches the shipping method you want to map, for example, due to the Owebia_AdvancedShipping plugin, you can add the mapping directly by entering the full shipping method code, e.g., for Owebia: owsh1_pickuppl. The method mapped in this field will override the mapping in the drop-down list above. |
Delivery Deadline In Days | The required numeric value needed to calculate the maximum delivery date.
|
Enable using Collect Address Totals | Enabling this option forces shipping costs to be calculated based on the delivery address – by default, to Poland. This configuration is recommended when using specific cart rules based on the delivery address that provide free shipping (for example, free shipping only to Poland) or non-native solutions that calculate shipping costs. By default, this option is disabled because it's not needed in standard cases and causes some minor delays in cart processing. |
Configuration View:
General Settings
Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->General Settings
Description of configurable fields:
Enable InPost Pay | Allows you to enable or disable this payment method. |
Enable Test Mode | Test mode is primarily used to test production just before the global launch with a real order and payment. Enable Test Mode only works when sandbox mode is disabled. After enabling this option (when sandbox mode is disabled), the InPost Pay widget will be visible only on pages where the URL contains the parameter: This allows you to test the entire purchase process on the production environment, including payment for the order using the production InPost Pay app for mobile devices, in such a way that customers are not yet able to see this functionality. After verifying the environment, it is necessary to disable test mode. |
Title | The name displayed for this payment method. |
New Order Status | The status that is set when an order is created with this payment method. |
Accept Payments from Countries | Whether payments are to be accepted from all countries or from selected countries. |
Accept Payments from Listed Countries | A list of countries to be used if accept payments from selected countries has been selected in the Accept Payments from Countries field. |
Minimum Order Value | The minimum order amount for this payment method. |
Maximum Order Value | The maximum order amount for this payment method. |
Use first name and surname from address instead of first name and surname of the customer | Allows you to transfer the first name and surname from address instead of the first name and surname of the customer to InPost Pay |
Role of image sent to InPost Pay | A drop-down list to choose which image should be sent to InPost Pay |
Send additional images to InPost Pay | A field defining whether a single photo or multiple photos should be sent to InPost Pay. The definition of photo sending also applies to the functionality of Bestselling Products. |
Assign Basket to Customer by Email Address | Default value: YES. If this configuration is enabled, Store baskets created by non-logged-in users and linked with InPost Pay will be assigned to the customer account in Magento during order processing, provided that the said account exists, based on the e-mail address of the account in the InPost Pay App. If this configuration is disabled, Store baskets created by non-logged-in users and linked with InPost Pay will remain as guest orders even if there is a Store account with the same e-mail address as used by the customer in the InPost Pay App. The above configuration does not affect baskets created by logged-in customers of the Store. Orders placed by them will be assigned to the account of the user logged in to the Store regardless of this setting. |
Allow Partial Invoice Refunds | Default: YES This is a natively supported Magento configuration field for payment plugins. If set to YES, an editable field for the number of products covered by the refund will appear in the refund form (a corrective invoice issued from the invoice confirming payment for the order). If set to NO, this field is not editable and the refund is treated as a full refund. |
Configuration View:
Sandbox
Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Sandbox
Description of configurable fields:
Switch InPost Pay to Sandbox Mode | Configuration to enable Sandbox test mode. |
Sandbox Client ID | Client ID received from InPost, used for authorization purposes in Sandbox mode. |
Sandbox Client Secret | Client Secret value received from InPost, used for authorization purposes in Sandbox mode. |
Sandbox Auth Token URL | The base InPost URL address where Sandbox mode authorization will be performed to retrieve the token used in further communication with the API. |
Sandbox Merchant Secret | Merchant Secret value received from InPost, needed to create refunds in Sandbox mode. |
Sandbox POS ID | ID assigned by InPost for Sandbox mode |
Sandbox IZI API URL | The base InPost URL address where the integration of the basket and orders will be implemented in Sandbox mode. |
Sandbox Client Merchant ID | Merchant ID assigned by InPost for the Sandbox mode. |
Configuration View:
Authorization Settings
Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Authorization Settings
Description of configurable fields:
Client ID | Client ID received from InPost, used for authorization purposes. |
Client Secret | Client Secret value received from InPost, used for authorization purposes. |
Auth Token URL | The base InPost URL address where authorization will be performed to retrieve the token used in further communication with the API. |
Merchant Secret | Merchant Secret value received from InPost, needed for creating refunds. |
POS ID | The ID assigned by InPost |
Client Merchant ID | Client ID assigned by InPost |
Configuration View:
Debugging Settings
Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Debugging Settings
Description of configurable fields:
Log Level | The level from which the information collected by the plugin will be logged in files from the most detailed information: DEBUG to the most critical: EMERGENCY |
Enable Log Anonymization | Flag to enable anonymization of data collected in the logs on Merchant's server. Enabled by default. Log data that is subject to anonymization: Form of data in logs: p**********l@example.com5*******4 (phone number)P***r (first name)K****l (surname) |
Configuration View:
IZI API Settings
Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->IZI API Settings
Description of configurable fields:
IZI API URL | InPost URL address where API resources related to the basket and orders from the InPost Pay mobile app are available. |
Basket lifetime | The number of seconds based on which the basket expiration date is calculated. Abandoned, out-of-date baskets will be deleted by the InPost Pay app after this date. |
Define Payment Methods | When this option is selected, you can specify which specific methods are allowed for purchases through InPost Pay. If the option indicates NO (default) - all methods agreed upon in the contract are available for customers purchasing through InPost Pay. If no method is configured despite selecting YES in this option - all payment options compliant with the contract will be available to customers. |
Synchronize available payment methods | A button that allows you to synchronize payment methods with the InPost Pay API |
Accepted Payment Methods in the InPost app | A multiple-choice list that allows you to determine which payment methods will appear in the mobile app for the basket. Available payment methods are synchronized once a day using cron. Note: this configuration must correspond to the mapping of delivery methods with cash on delivery. If cash on delivery payment method is configured, then it should also be mapped there. |
Enable asynchronous basket export | In case of a very high volume of traffic, baskets and server load issues, you can configure to delegate basket update requests to a queue. Note: the native functionality of Magento database-based queues is used here, rather than Rabbit MQ. For the functionality to work properly, it is necessary to configure when the process of consuming queued messages is to be run on the server admin side. |
Enable the removal of special characters and HTML code from product attributes sent to the InPost Pay Mobile App | The InPost Pay API and app currently do not support such characters. The configuration should be set to YES, if there are such characters in the product data |
Configuration View:
Consent mapping
Configuration path:
Store->Configuration->Sales->Payment Methods->InPost Pay->Terms and Conditions Mapping Settings
Description of configurable fields:
Use Legacy Consent Mapping | *YES (Default) - Uses the legacy mapping setup described below using native Magento consents.
NO - It uses a new form of consent configuration available in the tab: Stores->InPost Pay Terms And Conditions |
Magento consents | Select with consent selection. |
Requirement level | Select that allows to select the level of requirement of the relevant consent, available options include: REQUIRED_ALWAYS, REQUIRED_ONCE, OPTIONAL ADDITIONAL_LINK - a special option dedicated to several consents transferred as a single item to be selected, containing several links. |
Parent consent | In the case of ADITIONAL_LINK requirement level, this is an indication to which parent consent this link belongs. |
Link to consent | link to the full wording of the consent. |
Link label | In the case of consents linked by ADDITIONL_LINK, this is the word or phrase that will replace the "link" to the consent. |
New Configuration View:
Stores→InPost Pay Terms And Conditions
List of configured terms and conditions:
New InPost Pay Terms And Conditions form:
Form Fields | Description |
|---|---|
Title | Auxiliary title. Visible only in the Magento Admin Panel to facilitate recognition of consents in the list. |
Is Enabled | The flag responsible for whether a given consent should be shown or not. |
Store View | Specifying for which view(s) a given consent should appear - allows you to configure consents for different language versions. |
Visible As | Main Agreement - This is the basic consent type. It specifies that this consent will be displayed independently of other consents, independently next to a checkbox, and depending on the requirement setting, it will be required or not. Sub-Agreement - For Example: Where bold phrases are links to separate regulations, which are separately configured Sub-Agreements. |