Credit applications are the initial step in the Inbank financing process. Once the application is reviewed and accepted by the customer, a credit contract is created.
- API Request Flow with Down Payment and Partner Approval
API Request Flow
API Request Flow with Partner Approval
API Request Flow with Down Payment
API Request Flow with Dow...
Direct API Guide
Documentation version 2.05, 19.07.2024
Please note, that this is the archived version of the guide.Please note, that the given document is only applicable for partners integrating in Estonia and Latvia.
Inbank API for Partners is designed for integrating third-party applications to Inbank's credit system. The API aims to follow RESTful best practices as closely as possible to achieve its main goal — to be flexible and applicable to multiple use cases. The current document describes the API endpoints available to partners.
For any questions regarding the integration process, contact Inbank at:
- Estonia: integration@inbank.ee
- Latvia: integration@inbank.lv
Note the partner is responsible for authenticating the customer before the partner transmits customer data to Inbank. Acceptable authentication methods are ID card, Mobile ID or Smart-ID. The partner must be able to prove the customer's authentication to Inbank.
Full integration with Inbank API gives merchants access to the following Inbank products:
Hire Purchase
The Inbank Hire Purchase solution gives customers the opportunity to pay for purchases in installments with an affordable interest rate. Read more about Inbank Hire Purchase on our website.
Split into parts
This payment solution offers clients to buy goods and services and pay for them later in several equal instalments. Split into parts is free of charge for customers, while merchants get paid upfront in full the next working day. Read more about this payment solution on our website.
Estonia:
| Environment | API | Partner Portal |
|---|---|---|
| Test | https://demo-api.inbank.ee/partner/v2/ | https://demo-partner.inbank.ee/ |
| Production | https://api.inbank.ee/partner/v2/ | https://partner.inbank.ee/ |
Latvia:
| Environment | API | Partner Portal |
|---|---|---|
| Test | https://demo-api.inbank.lv/partner/v2/ | https://demo-partner.inbank.lv/ |
| Production | https://api.inbank.lv/partner/v2/ | https://partner.inbank.lv/ |
*Note that step 6 is only required if the flow is using SMS signing.
* Note that for all API flows in case of income_proof_required decision with income_proof_type returned as manual_internal_verification, instead of steps 2 and 3 the manual statement upload should be performed. More information can be found here.
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 for Estonia: https://demo-api.inbank.ee
Demo API environment for Latvia: https://demo-api.inbank.lv
For testing purposes, the system returns preconfigured decisions. Positive decisions are given for amounts 0 - 500, 15 000 - 16 000.
The credit application process may include an OTP code exchange via SMS. The demo environments do not send out SMS messages. If you are testing the Split into parts payment product, the SMS message is hardcoded to value 0000.
To test the financing products in Estonia and Latvia, you can safely use your own Estonian/Latvian ID-code and ID-card, as the demo environment does not initiate real binding contracts. Alternatively in Estonia, you can use our demo user, the identity code of which is 10101010005. Besides the identity code, you will also need a name and a phone number for authentication and signing.
To use an ID-card or Mobile-ID in the demo environment, you need to register them at:
- ID-card - https://demo.sk.ee/upload_cert/
- Mobile-ID - https://demo.sk.ee/MIDCertsReg/
You can also use Smart-ID by downloading the following apps:
To use Smart-ID for testing, your account level should be Qualified. You can check the account level at https://sid.demo.sk.ee/portal/login.
Inbank will send callbacks about changes to the credit contract status. Contracts can have the following statuses:
| Status | Description |
|---|---|
unsigned | A contract has been created, but has not yet been signed by the customer and/or Inbank. |
| signed | The contract has been signed by both the customer and Inbank. For the flow which includes merchant approval, this state indicates that the credit has been granted by Inbank and the system is now awaiting approval from the partner to activate the contract. |
| activated | This is the target state: credit contract between customer and Inbank has been activated, merchant is liable for the delivery of goods/services. |
| cancelled | The credit contract has been cancelled. This state applies only to contracts which previously were For the flow which includes merchant approval, |
| terminated | An existing credit contract has been terminated. This state can only be applied to contracts which previously were activated. |
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:
{
"error": [
"unauthorized"
]
}HTTP header Content-Type application/json is expected in all requests, unless otherwise specified in the endpoint description. Example:
Content-Type: applications/json
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:
| Status in callback message | Description |
|---|---|
| Decision related callbacks | |
| POSITIVE | The credit application received a positive decision and the customer can move forward in the financing process. |
| NEGATIVE | The credit application received a negative, Inbank cannot offer financing to the customer. |
| FAILED | The decision process has encountered issues and the decision cannot be made. If this status persists, please contact the Inbank integration team. |
| INCOME_PROOF_REQUIRED | To make a decision Inbank needs the customer to provide income proof documents. |
| Contract related callbacks | |
| UNSIGNED | The contact has been created and is now waiting for customer signature. |
| SIGNED | The customer has signed the credit contract. |
| ACTIVATED | The credit contract is now activated, the financing of the purchase has been completed. |
| CANCELLED | The contract has been cancelled. |
| TERMINATED | The previously activated contract has been terminated. |
| ACTIVATION_REQUIRES_PARTNER_APPROVAL | The financing has been granted by Inbank. Partner's approval is now needed for contract activation. Applicable if the flow requires merchant approval of credit contracts. |
| DOWN_PAYMENT_PAID_BY_CUSTOMER | The customer has successfully paid the required down payment. Applicable if the flow includes making a down payment. |
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.
Callbacks are sent as http POST requests, ("Content-Type" => "application/x-www-form-urlencoded"). The POST form has the following structure:
| Parameter | Example value | Description |
|---|---|---|
| message | %7B%22type%22%3A%22DECISION%22%2C%22status%22%3A%22POSITIVE %22%2C%22creditApplicationUuid%22%3A%2259d2194c-634f-4632-91b6-300b58e628ce%22%7D | URL-encoded JSON structure containing information about the financing process. |
| hmac | c196e985640a6291723dc2717d264f82e70126c34b107f3be5b22201cb147c9 8b9709f5184a7f2fe82684d6086eee07df8a46c28fc0edfdd14fd306579244664 | HMAC value. For more details, see HMAC calculation logic described in the Callback authenticity chapter. |
| timestamp | 1549411200 | Current Unix timestamp at issuing server. See https://en.wikipedia.org/wiki/Unix_time for more details. |
Request header
{"Content-Type":"application/x-www-form-urlencoded"}Request body
message=%7B%22type%22%3A%22DECISION%22%2C%22status%22%3A%22INCOME_PROOF_REQUIRED%22%2C%22creditApplicationUuid
%22%3A%22bb3853ce-2034-499e-8b08-42625fdf068b%22%7D&hmac=29087d41b6171ee7598c7789b507429a8227cdf46e68d6f14626f
62ef6d1a5894f3fbdc31c96e885e2dafde7abf24054a8c67a923c58dc86749208abb8a1f721×tamp=1722587395319The 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.
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:
key = your_api_key;
req_timestamp = request[timestamp];
req_message = request[message];
req_data = req_timestamp+'.'+req_message;
v_hmac = hmac(“sha512”, key, req_data);JavaScript example (Postman):
key = your_api_key;
req_timestamp = decodeURIComponent(request[timestamp]);
req_message = request[message];
req_data = req_timestamp + '.' + req_message;
v_hmac = CryptoJS.HmacSHA512(req_data, key);PHP example:
$key = $settings->api_key;
$req_timestamp = $_POST['timestamp'];
$req_message = stripslashes($_POST['message']);
$v_hmac = hash_hmac('sha512', $req_timestamp . '.' . $req_message, $key);The API endpoints cover all the functionality necessary for full integration with Inbank systems.
Please note: Inbank payment methods should be available only for cart values that are within the price range agreed with Inbank. If you would like to receive the price range and other details of your Inbank product over API, please use the GET /products endpoint.
Languages
Servers
Demo environment
https://demo-api.inbank.ee/
Live environment
https://api.inbank.ee/