Flow Overview

URLs

Demo Environment

Inbank provides a separate environment for development and integration testing. The testing environment remains available after the integration with Inbank has been completed. The testing and production environments differ, each having individual data sets.

Demo API environment: https://demo-api.inbank.pl

For testing purposes, the system returns preconfigured decisions. Positive decisions are given for amounts 0 - 500, 15 000 - 16 000.

Note that the credit application process may include an OTP code exchange via SMS. The testing environment does not send out SMS messages, but lists them in the simulator available at: https://demo-sms.inbank.eu/. In the search field at the top of the page, you need to specify the phone number you have indicated in the credit application and click Search. The simulator will then list the messages sent to that number.

Credentials for the SMS simulator:

• username: inbank
• password: XUJc8CncaVKvkEQvNgsTvqdw

API Request Flows in Case of Positive Decision

API Request Flow

* Note that steps 3 and 8 are only required if the flow is using SMS signing.

** Note that steps 10, 11, and 12 are needed if at step 9 you get process_status = waiting_for_customer_digital_verification. If at step 9 you get process_status = activated no further steps are needed.

API Request Flow with Partner Approval

* Note that steps 3 and 8 are only required if the flow is using SMS signing.

** Note that steps 10, 11 are needed if at step 9 you get process_status = waiting_for_customer_digital_verification. If at step 9 you get process_status = waiting_for_partners_confirmation then proceed to step 13 directly.

API Request Flows in Case of income_proof_required Decision

API Request Flow

* Note that steps 3 and 11 are only required if the flow is using SMS signing.

** Note that if the account statement was uploaded manually and the flow is to include AIS verification then if at step 12 the process_status = waiting_for_customer_digital_verification steps 5 and 6 need to be done after step 12.

API Request Flow with Partner Approval

* Note that steps 3 and 11 are only required if the flow is using SMS signing.

** Note that if the account statement was uploaded manually and the flow is to include AIS verification then if at step 12 the process_status = waiting_for_customer_digital_verification steps 5 and 6 need to be done after step 12.

Authentication

Inbank will provide you with an API key, used for authentication, and a unique identifier of your shop, required for building API URLs. The API-key should remain private at all times.

To obtain access to the API endpoints, place the API key in the Authorization header of the request. The Authorization header should have the Bearer scheme and your API key, for example:

Authorization: Bearer e93174d3b9158a01c861c65fab0e7f96

The API server will then verify the API key authenticity.

In most cases, you will need to use a shop identifier (shop_uuid) in the path of the API endpoint. Shop identifier is provided to you by Inbank together with the API key.

In case of unsuccessful authorization, the system will return the following message:

Content-Type

HTTP header Content-Type application/json is expected in all requests, unless otherwise specified in the endpoint description. Example:

Content-Type: applications/json

Callbacks

When sending a credit application via Inbank Partner API the e-shop has the option to provide the callback_url - the URL to which Inbank will send server-to-server callback notifications on financing process status change events. Callback requests are lightweight triggers for initiating activities on the merchant side. They contain only minimal information.

Inbank sends callbacks about the following state transition events:

To avoid processing accidental or malicious traffic to callback endpoints, the handlers should first verify the authenticity of the request. For more details, see the Callback authenticity validation chapter.

E-shop should process the incoming messages, at a minimum, in the following way:

• Validate the authenticity of the request, to avoid further processing of invalid traffic.
• Look up the credit application UUID either from the incoming message, or from the internal database as it was returned when the application was sent.
• Inspect the status message and process the order payment status based on it.
• Redirect the user to the respective dialog, i.e. the “payment complete” page.

Note in case duplicated callbacks should arrive for a single payment session, please make sure that only the first callback is processed.

Request Structure

Callbacks are sent as http POST requests, ("Content-Type" => "application/x-www-form-urlencoded"). The POST form has the following structure:

Request header

Request body

Callback Message Content

The message contains minimal information, it is meant as a trigger to obtaining more detailed information over Partner API. The message body contains:

• type - type of the Inbank entity the status of which is reflected in the callback. Possible types are CONTRACT and DECISION.
• creditApplicationUuid - credit application UUID.
• status - status of the financing process at the moment of message dispatch.

Callback Authenticity Validation

We use message authenticity hash (HMAC) transported within the POST request form field hmac.

To validate the message authenticity you need to calculate the verifying HMAC based on data from the request and your secret api_key, and compare the calculated HMAC with the HMAC value passed in the request.

Verifying HMAC is calculated as SHA512 HMAC, over the timestamp and message from the request, concatenated with . delimiter. Your shop API key is used as HMAC secret.

Pseudocode for example verifying HMAC calculation:

JavaScript example (Postman):

PHP example: