Authorization and Technical Requirements

In this section, you will find information regarding authorization in communication with InPost Pay, and information on how to configure the Merchant account and generate access credentials (client_id and client_secret).

On this page:

Authorization

To authenticate customer communications with InPost Pay (Basket App), the OAuth 2.0 standard is used. In the case of service to service communications – without the logged user context, client_credentials flow a OAuth is used (https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/).

• The Merchant receives their client_id and client_secret

• They collect an access token

• They sign each request. The access token should be provided in the header Authorization: Bearer PLACE-TOKEN-HERE

• The resource server verifies the token and identifies the customer

The token endpoint is fixed, and can be a configuration parameter on the customer's side:

• Production environment
  https://login.inpost.pl/auth/realms/external/protocol/openid-connect/token

• Sandbox environment
  https://sandbox-login.inpost.pl/auth/realms/external/protocol/openid-connect/token

Token Collection:

Request

Response

Example implementation in PHP

• We are creating a service interface that will be responsible for retrieving the bearer access token.

  <?php declare(strict_types=1); namespace Iteo\InpostPayClient\Client; use Iteo\InpostPayClient\SDK\Core\Exceptions\InpostPayEndpointException; /** * Interface used for creating bearer token, needed to communication with Inpost Pay. */ interface InpostPayBearerServiceInterface { /** * Method that creating bearer access token for given merchant credentials. * * @return string Bearer access token * * @throws InpostPayEndpointException */ public function getBearerToken(): string; }

• We are creating an exception, which we will return if the token retrieval fails.

  <?php declare(strict_types=1); namespace Iteo\InpostPayClient\SDK\Core\Exceptions; class InpostPayEndpointException extends \Exception { final public function __construct(string $message = '', int $code = 0, \Throwable $previous = null) { parent::__construct($message, $code, $previous); } public static function createClientException(\Throwable $throwable): self { return new static( sprintf('InpostPayClient, error occurred when creating http client with bearer token. Exception message: %s', $throwable->getMessage()), $throwable->getCode(), $throwable ); } }

• We are creating a service implementation that retrieves an access token using the getBearerToken method.

  <?php declare(strict_types=1); namespace Iteo\InpostPayClient\Client; use League\OAuth2\Client\Provider\Exception\IdentityProviderException; use League\OAuth2\Client\Provider\GenericProvider; use Iteo\InpostPayClient\SDK\Core\Exceptions\InpostPayEndpointException; /** * PHP Bearer Service implementation used for creating bearer token, needed to communication with Inpost Pay. */ final class InpostPayBearerService implements InpostPayBearerServiceInterface { private string $clientId; private string $clientSecret; private string $urlAccessToken; private ?string $urlAuthorize; private ?string $urlResourceOwnerDetails; //Zamienić w zależności od środowiska private const URL_ACCESS_TOKEN = 'https://sandbox-login.inpost.pl/auth/realms/external/protocol/openid-connect/token'; public function __construct(string $clientId, string $clientSecret, string $urlAccessToken = self::URL_ACCESS_TOKEN, string $urlAuthorize = null, string $urlResourceOwnerDetails = null) { $this->clientId = $clientId; $this->clientSecret = $clientSecret; $this->urlAccessToken = $urlAccessToken; $this->urlAuthorize = $urlAuthorize; $this->urlResourceOwnerDetails = $urlResourceOwnerDetails; } /** * {@inheritdoc} */ public function getBearerToken(): string { $provider = new GenericProvider([ 'clientId' => $this->clientId, 'clientSecret' => $this->clientSecret, 'urlAuthorize' => $this->urlAuthorize, 'urlAccessToken' => $this->urlAccessToken, 'urlResourceOwnerDetails' => $this->urlResourceOwnerDetails, ]); try { return $provider->getAccessToken('client_credentials')->getToken(); } catch (IdentityProviderException $exception) { throw InpostPayEndpointException::createClientException($exception); } } }

• In order to use OAuth2.0, the following library was used: league/oauth2-client - Packagist

Merchant account configuration - production environment

1. Gain access to the production environment

• You will gain access to Merchant panel once the Transaction Handling and Settlement Contract is signed.

• If you have not yet signed the contract, contact your InPost sales representative or use the form available in the "For Business" section in the "InPost Pay Offer" tab.

2. Log in to the Merchant panel
   Panel address: https://merchant.inpost.pl

• Log in with the e-mail address indicated in the contract in the ADMINISTRATOR field.

• If you are logging in for the first time – register an account using the administrator e-mail address provided in the contract, and follow the instructions provided in the e-mail.
  Issues with logging in? Contact your sales representative or write to bok.pay@inpost.pl

3. Fill in your store details

• After logging in, you will see your store details.

• Click on the yellow EDIT button in the upper right corner of the page to enter the details required to generate the integration keys.

Open

Fill in all fields on the form:

• Name of the store– will be visible in the InPost Mobile app.

• Category – choose the category that best suits the store's business.

• Technology – select the platform used by your store.
  For API integration, select API Integration and specify the URL for communication with the store's backend.

4. Add your store logo
   Your logo will be visible in the InPost Mobile app, so it is important that it is added in the correct quality and format:

   1. Paste a link to the logo, available on a public server (it cannot be e.g. Google Drive or cloud), it is best if the link leads to the logo on your store's website (How to upload a logo to your store’s server?)

   2. The logo must not be larger than 50 kb.

   3. The logo must be in both light and dark versions (depending on which version of the application the user is using)

   4. Your logo should be sized to a minimum width of 108px and a minimum height of 40px to be clearly visible. Make sure that your logo does not include margins for better visibility in the application. You can upload in SVG format and the max file size is 50kb.

   5. If the logo you want to provide is in SVG format, make sure that the "Preserve Illustrator Editing Capabilities" option is not selected when rendering the file.
      NOTE! A preview of the logo is available to the left of the link. Make sure the logo is correct!

Save the data by clicking SAVE in the upper right corner.

Open

5. Generate credentials

To generate client_id and client_secret, you need to fill in the details of each store.

Open

Once all the data is entered, go to the InPost Pay Keys tab and generate the necessary data by clicking the CREATE INPOST PAY KEYS button on the right side of the screen.

Open

Next you will see Client ID and Client Secret, copy and paste them in your store panel.

Open

• Client ID – copy and paste into the store panel

• Client Secret – to generate use the RESET CLIENT SECRET button

• Merchant Client ID – this is the key needed for integration with Widget 2.0. A complete description of this item can be found here Widget 2.0

• POS ID – copy and paste into the store panel

Open

Reset Client Secret – you can reset Client Secret at any time using the three dots icon on the right side of the table.

Open

Open

IMPORTANT: Each generation of a new Client Secret deactivates the previous one – be sure to update it in your store.

Open

6. API Keys – Merchant Secret (optional for ERP/API integration)

• If you are integrating refunds and transactions using the API, you will find the necessary credentials by selecting API Keys in the menu item

• Generate a Merchant Secret Key using the yellow button in the upper right corner of the CREATE SECRET screen
  
  

Open

• Copy Merchant Secret and paste it into your store panel

  Open

  

• You can reset Merchant Secret at any time by clicking Reset Secret

• After the reset, you need to update the Merchant Secret in your store - until then, the refund API will not work.

• Reset Merchant Secret only when necessary.

Open

Open

Open

If you reset Merchant Secret, this results in the need to enter a new one in your online store, until then API communication will be inactive. We recommend resetting only in necessary cases.

REMEMBER! Don't share it with anyone!

Do not share credentials with third parties.

7. Setting up automatic notifications (transaction webhooks)
   In the Automatic Notifications section, you can configure the URL address to which webhooks for payments, refunds, and settlements should be sent. This will allow your ERP system to react in real-time to transaction-related events. Make sure the address is correct and accessible from the public network.
   
   

   Open

   

Do you have more stores? If you have more than one store, when you click on the drop-down list on the left, you can switch between your stores and see a list of stores for which a service contract has been signed.

Open

If you have questions, please contact us: bok.pay@inpost.pl

How to obtain a link to your logo?

1. Copy it from your store page

   1. Right-click on your store's logo

   2. Select "Open image in new tab"

   3. Copy the link from the url bar

2. WooCommerce (based on WordPress)
   Adding an image to your media library:

   1. Log in to your WordPress admin panel.

   2. Select "Media" > "Add New" from the menu on the left.

   3. Click the "Select files" button and select the image from your computer or drag the file directly into the browser window.

   4. Once the upload is complete, click on the added image to open its details.

   5. In the right panel you will find the "File URL" field – this is the public link to your image. Copy it and use it as needed.

3. PrestaShop

   Adding an image to your media library:

    To add an image and obtain a public link to that image, you can use the following method:​

   1. Log in to your PrestaShop admin panel.

   2. Go to "Catalog" > "Products".

   3. Select the product for which you want to add an image, or create a new one.

   4. In the "Images" section, click "Add file" and select an image from your computer.

   5. Once uploaded, the image will be assigned to the product. To obtain a public link to that image:

      1. Go to the product page in the store (frontend).​

      2. Right-click on the image and select "Copy image address".​

      3. The copied address is the public link to your image.​

Note: You can also use an FTP client (such as FileZilla). Place the uploaded files in the /img/ directory. This way requires basic knowledge of FTP server operation. If you have difficulties, contact your administrator or find a tutorial on Google, e.g. by typing the phrase "how to upload a file via FTP".

4. Magento

   Adding an image to your media library:

   1. Log in to your Magento admin panel.

   2. Go to "Content" > "Media" > "Insert Images".

   3. Click "Add new image" and select a file from your computer.

   4. Once uploaded, the image will be added to the media library.

   5. To obtain a public link to the image:

      1. Go to "Content" > "Media" > "Library".​

      2. Find the image you added, click on it, and then copy the displayed URL – this is the public link to your image.​

   Note: In Magento, images are often stored in /pub/media/ directory, so the public link will be structured as follows: https://twojadomena.com/pub/media/file_name.jpg.

Merchant account configuration - sandbox environment

To access the Sandbox environment, fill out and submit the contact form by selecting the "Online store" option and the "Sandbox" tab.

InPost Mobile test application

For testing purposes, we also provide you with access to our InPost Mobile test apps:

• install iOS by downloading the app from the link:
  Join the InPost Mobile (Sandbox) beta

• install Android by downloading from the file
  

If you downloaded the file to your mobile device and it was saved as an archive named "InPost Mobile [version_number] Sandbox.apk.zip”, rename it and remove the ".zip" extension. Once the changes are saved, you should have a file with the .apk extension, which will automatically install/update the application when opened. If, despite renaming the file, you still can't install the app, make sure you have been granted the proper permissions to install the app in your device settings.

Want to test on the local environment?

In order to provide remote access to the local environment, an additional workaround is required in the form of tunneling traffic from the public domain to a local address. Without such a workaround, there is no way to connect directly to the local environment.
Recommended solution
The current recommended tool is ngrok, which allows you to quickly set up a tunnel between the public URL and the local environment. All you need is a free account that provides one permanent public domain. This domain can redirect traffic to a local application or a closed test environment.
Requirements
After creating a free public domain, you need to provide its address in the Contact -> Sandbox form to receive credentials and all test traffic can be routed to that address.

Technical requirements on the Merchant's side

Outbound traffic from InPost to the Merchant for InPost's Proxy IP 34.118.93.24, 34.116.145.216.

Mechanism used to block communication with the Merchant in case of errors

When communicating synchronously with the Merchant, there may be a number of system-to-system communication issues that affect conversions and customer use of the InPost Pay app, which include:

• requests taking too long to process due to a drop in the Merchant's system bandwidth

• the Merchant's service may be overloaded or waiting for other resources

• the Merchant may respond in a way inconsistent with the contract (e.g. missing required data), resulting in a validation error

• the Merchant returns an error regarding server problems (5xx)

In order to maintain high conversion of baskets and orders and high-quality customer service, the InPost Pay app has implemented a mechanism to block communication with the Merchant in the event of the aforementioned errors.

Rule to block communication between InPost Pay app and the Merchant:

If there are a minimum of 20 queries to the Merchant within 120 seconds, in which a minimum of 90% will throw errors:

• HttpServerErrorException e.g. response.status: 500

• ResourceAccessException e.g. Merchant timed out

• ResponseNotValidException e.g. Merchant responds with an error message 200, but in the passed response.body the datum or data is incorrect (e.g. required data is missing), due to which the app cannot process the message correctly,

then the InPost Pay app will block communication with the Merchant.

If the Merchant’s communication has been blocked, when attempting to call a method to InPost Pay they will receive error 409 with a message reading:

{ "error_code": "MERCHANT_DISABLE", "error_message": "Merchant with given id: <merchant_id> is DISABLED" }

In order to unblock communication, the Merchant must contact InPost Pay by submitting a ticket to integracjapay@inpost.pl.