Authorization and Technical Requirements

This chapter contains information regarding authorizations in communications with the InPost Pay app, and the configuration of the Merchant's account, and generating access (client_id and client_secret).

On this page:

1 Authorization
- 1.1 Example implementation in PHP
2 The configuration of the Merchant's account - production environment
3 The configuration of the Merchant's account- sandbox environment
- 3.1 InPost Mobile test application
4 Technical requirements on the Merchant's side

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

The Merchant generates client_id and client_secret for the production environment through the Merchant's panel according to the manual.
The Merchant receives client_id and client_secret for the sandbox environment from InPost upon notifying through the contact form according to the manual.

They collect an access token
They sign each request. The access token should be provided in the header Authorization: Bearer W-TYM-MIEJSCU-NALEZY-UMIESCIC-TOKEN
The resource server verifies the token, and identifies the customer

All the requests sent to the server require entering the right and valid access token, which belongs to the particular User.

The token generated has a specified validity (as defined in expires_in, which is returned together with the token), and it is not necessary to download a new token at each request.

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

curl --location 'https://sandbox-login.inpost.pl/auth/realms/external/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=sandbox' \
--data-urlencode 'client_secret=qwertyuiop' \
--data-urlencode 'grant_type=client_credentials'

Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiw...",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "api:inpostpay"
}

Errors that may occur when generating a token:

Invalid client credentials- In the case of providing wrong client_id
Invalid client secret- In the case of providing wrong client_secret
Missing form parameter: grant_type- In the case of missing grant_type: client_credentials

Example implementation in PHP

We create the interface of the service, which will make it possible to download 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 create an exception, which will be returned in the case of a failed token download.
<?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 create an implementation of the service, which downloads 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); } } }

To use OAuth 2.0, the library was used https://packagist.org/packages/league/oauth2-client?query=https%3A%2F%2Fpackagist.org%2Fpackages%2Fleague%2Foauth2-client%3Ftype%3Dcontao-module%26page%3D40&type=contao-module#2.7.0

The configuration of the Merchant's account - production environment

In order to access the production environment, sign a Contract for Handling and Settling Transactions. If you haven't signed the contract yet, get in touch with your InPost sales representative or use the form included in the section "For Business" in the tab "InPost Pay 'Offer".

After signing the Contract log in to the https://merchant.inpost.pl/ site using the email address provided in the contract in the ADMINISTRATOR field.
If this is your first login and you do not have an account, register a new account using the administrator's email address provided in the contract and follow the email instructions.
NOTE! If you cannot log in using the administrator's email address, please contact your sales representative or write to bok.pay@inpost.pl
After logging in, you'll see a list of stores for which a service contract has been signed.
To generate client_id and client_secret, you must complete the detailed information for each store using the yellow button next to the store name.
PLEASE REMEMBER! The completed data will be visible in the InPost Mobile application for users, ensure their correctness.
Complete all required data on the form:
1. Store name – enter the name of the store, which the customers will see in the InPost Mobile app while shopping
2. Technology – choose the technology your online store is based on.
  NOTE! In the case of custom integration via API, select "API Integration" – then you must also provide a url for communication with your store's backend so that communication between the service and your store can take place.
Your store's logo will be visible in the Shopping tab in the InPost Mobile application, so it is important that it is added in the correct 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
2. Logo cannot be larger than 50 kb.
3. The logo must be in both a light and dark version (depending on which version of the app the user is using)
4. Logo should be sized to a minimum width of 108px and a minimum height of 40px. Make sure your logotype does not contain margins for better visibility in the application. You can upload the logo in SVG format, remember that the maximum file size is 50 kb.
5. If the logo you want to specify 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!
After completing all the data, click the button SAVE CHANGES.
If all the stores' data is already filled in, you can proceed to generating credential. To do this, use the 'expand' arrow next to the store for which you want to get data.
A page will then expand with additional information:
1. Client ID - copy and paste in your store panel
2. Client Secret - to generate use the button RESET CLIENT SECRET
3. Merchant Client ID - this is the key necessary for integration with Widget 2.0. A complete description of this element can be found here - Widget 2.0
4. POS ID - copy and paste in your store panel
5. Return password - if you integrate your ERP system with the API for transactions and returns, you will need this password, otherwise this data is optional for you and you do not have to use it. You can find a complete description of this service here https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/172130316
6. In this tab you do not have to fill out anything, you can only view the secret or reset it.

REMEMBER! Don't share it with anyone!

Client Secret – after using the button RESET CLIENT SECRET you will see your Client Secret - copy and paste it into your store panel.

NOTE! Each time you use this button, the Client Secret will be reset, which will require you to enter a new Client Secret in your store panel. Until then, users will not be able to finalize purchases via InPost Pay.

Return password - if you integrate your ERP system with the API for transactions and returns, you will need this password, otherwise this data is optional for you and you do not have to use it. Using this button you can reset your password. You can find a complete description of this service here - https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/172130316.

To generate Return password for the first time, use the button “Reset return password”.

NOTE! If you reset your password, it will require you to enter a new one in your online store, until then API communication will be inactive. We recommend resetting your password only when absolutely necessary.

The configuration of the Merchant's account- sandbox environment

In order to gain access to the Sandbox environment, complete and send the Contact form by using the option Dla Biznesu and the Sandbox tab.

InPost Mobile test application

For the needs of the tests, we also make our InPost Mobile test applications available:

install iOS by downloading the app using the link
https://testflight.apple.com/join/ey6Yherd
install Android by downloading from the file

Make sure that, before starting the tests, make sure that you have the app's latest version.

Technical requirements on the Merchant's side

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

Developer Documentations