InPost Pay - Magento (Widget 2.0) [ENG]

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

  • New version: 2.4.2 (16.12.2025 r.)

    •  

  • 2.4.1 (26.11.2025 r.)

    • Optimization of the mass order processing process

  • 2.4 (05.11.2025 r.)

    • A special module has been prepared to support Hyva Theme and Hyva Checkout

    • Handling of timeout errors

    • Changes in the button layout settings

  • 2.3.1 (24.10.2025r.)

    • Adaptation to the OwebiaShipping module

  • 2.3 (02.10.2025 r.)

    • Purchase of Digital Products and Electronic Delivery

    • Modification of Return Functionality and Handling of Partial Returns

    • Modification of Consent Mapping

    • Additional Variant of Coupons ONLY_IN_APP

  • 2.2.3 (25.08.2025)

  • 2.2.2 (07.08.2025)

    • Added the handling of free delivery set by Cart Rule with one of the conditions depending on the shipping country equals Poland.

    • Added compatibility with newer Magento 2 Open Source v2.4.8-p1 on PHP 8.3

    • Added compatibility with older Magento 2 Open Source v2.4.6 on PHP 8.1

  • 2.2.1 (16.07.2025)

    • Added region determination based on postal code

    • Added the ability to pass a link to bestseller products synchronized with the InPost Pay API

    • Added requirement for EAN for bestseller products

    • Modification of fetching the list of available payment methods

  • 2.2 (04.06.2025)

    • Added support for e-mail addresses dedicated to communication related to order processing

    • Added Bestseller Products Settings

    • Added Description of bestseller products functionality

  • 2.1.0 (12.05.2025)

    • Added ability to transfer discount codes to the application - configuration description

    • Added support for promoted products - configuration description

    • Transfer of product photos in two sizes (small size, normal size

    • Added validation when transferring consents to the application (maximum 10 consents)

    • Added the ability to anonymize data in logs to plugin configuration - configuration description

    • Ability to enable asynchronous shopping basket export - configuration description

  • 2.0.7 (26.03.2025)

  • 2.0.6 (14.03.2025)

    • Added separate processing of refunds for the Refund and Refund Offline options in the Magento admin panel. The former creates an InPost Pay transaction refund and the latter creates only the Magento Credit Memo without an online refund.

    • Fixed an error that occurred when the module was installed but not configured.

  • 2.0.5 (05.03.2025)

  • 2.0.4 (31.01.2025)

    • General Settings - Assignment of baskets to a customer by e-mail address.

  • 2.0.3 (17.01.2025)

    • Integration with Widget 2.0

    • Transmission of two order numbers (technical number and number displayed to the customer)

    • Option to configure widget visibility on production for testers only

    • Display of order payment method information in the Magento admin panel

    • Support for logs on the module side

    • Transfer of module version that is currently being used in the API.

 

On this side:

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:

 

 

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.
It is very important that when configuring this mapping, the price of the delivery method assigned to this option must correspond to the cost of the Weekend Parcel and Cash on Delivery options.

For example:
Standard - PLN 10
Weekend Parcel - PLN 12 (in the application: option +PLN 2 to standard shipping)
Cash on Delivery - PLN 14 (in the application: option +PLN 4 to standard shipping)
Cash on Delivery on the Weekend - PLN 16 (in the application: a combination of +PLN 2 and +PLN 4 options)

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.
It is very important that when configuring this mapping, the price of the delivery method assigned to this option must correspond to the cost of the Weekend Parcel and Cash on Delivery options.

For example:
Standard - PLN 10
Weekend Parcel - PLN 12 (in the application: option +PLN 2 to standard shipping)
Cash on Delivery - PLN 14 (in the application: option +PLN 4 to standard shipping)
Cash on Delivery on the Weekend - PLN 16 (in the application: a combination of +PLN 2 and +PLN 4 options)

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:

image-20251027-130651.png
image-20251027-130717.png

 


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: ?showInPostPay=true

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:

image-2025-8-11_11-51-47.png

 


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:

image-2025-8-11_11-52-5.png

 


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:

image-20250117-145311.png

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:
client_secret
merchant_secret
first names/surnames
e-mail addresses (the parts before @ and domain)
NIPs (Tax Information Numbers) and Business Names
Addresses (street names, cities, post codes, building numbers)
phone numbers

Form of data in logs:

p**********l@example.com
5*******4 (phone number)
P***r (first name)
K****l (surname)

 

Configuration View:

image-2025-8-11_11-52-29.png

 


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:

image-2025-8-11_11-52-51.png

 


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.

  • The above functionality will be removed in the future, it is left temporarily for backward compatibility purposes.

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

image-20251009-153318.png

List of configured terms and conditions:

image-20251009-153448.png

New InPost Pay Terms And Conditions form:

image-20251009-153526.png

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 -
[optional/advanced configuration] A special type of consent combined with another main consent. It allows you to configure one or more sub-consents within a single checkbox, placed as links leading to separate regulations.

For Example:
I confirm that I have read the Terms and Conditions and agree to the Privacy Policy. The full text of the consent can be found at this URL.

Where bold phrases are links to separate regulations, which are separately configured Sub-Agreements.