Skip to content
/
Authorization Header

ePOS Short Flow

Introduction

Documentation version 2.01, 03.10.2024

Please note, that this is the archived version of the guide.

Here at Inbank we strive to help our partners sell more by simplifying purchases and making financing more accessible to customers. For exactly this reason we offer a number of sales financing solutions. Our most known credit offering is hire-purchase, also known as payment by installments.

There are several methods of how partners can integrate with Inbank, this document covers our e-POS solution. With Inbank e-POS, partners only need to add Inbank as a payment method and redirect clients to our environment, Inbank will take care of all the rest. After a successful financing process we will redirect the customer back to you.

Inbank e-POS is supplemented with Inbank Partner Portal where merchants can see detailed overview of submitted credit applications, create applications for customers and conduct contract withdrawals.

For any questions regarding the e-POS integration process, contact Inbank at integration@inbank.ee. We will be happy to help.

Flow Overview

In general, the flow looks like this:

Inbank also sends server-to-server notification messages to ensure delivery of information about the payment session even if the customer does not return to the e-shop.

Inbank will provide a link to the detailed terms and conditions of credit, which can then be made available to customers.

The payment day of all credit installments is set automatically to the default system value.

Inbank API for partner integration (Partner API) is made available for the systems integration on request basis.

Demo Environment

Inbank provides a separate environment for development and integration testing. The demo environment remains available during the later life cycle of our cooperation, after the integration on production environment has been launched. The demo and production environments are different, each having individual data sets.

Note that the access credentials and product codes are different in the production environment. You will be provided production specific information.

For testing purposes, the demo environment returns preconfigured decisions. For the Inbank Hire Purchase Estonia payment product, a positive decision is 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, but list 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. Inbank will provide you with the credentials necessary to access the SMS simulator.

Guidelines for Integration Implementation

API Connectivity

Before you can initiate a session, Partner API connectivity must be configured.

Inbank will provide you an API key, used for authentication, and a unique identifier of your shop, required for building API URLs (for example POST /shops/YOUR_SHOP_UUID/pos_sessions). The keys should remain private at all times.

Authentication

The authentication process consists of the following two steps:

  1. Merchant places the API key in the Authorization header of the request.
  2. API server verifies the API key authenticity.

The easiest way to test that your API key is working correctly is to send a GET /ping request. On successful authentication API will respond with message: pong.

Authorization Header

Authorization header must have the Bearer scheme and value of your API key, for example:

Authorization: Bearer e93174d3b9158a01c861c65fab0e7f96

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

HTTP codeDescription
401Unauthorized
{
    "error": [
        "unauthorized"
    ]
}

Content-Type

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

Content-Type: application/json

Payment Session State Model

For the easiest integration we have designed the session status model to be similar to other payment channels that the e-shop integrates with.



StatusDescription

pending

A session is created;
Credit application may be or not be in progress;
Positive but not accepted credit decisions also remain in this status until they expire.
cancelledThe customer has cancelled the process.

granted

Credit has been granted to the customer, there are no obstacles from the Inbank side for sales completion.
The process is now waiting for merchant's approval, if configured so.
If the flow is configured not to wait for merchant's approval, this state may be omitted (see note below).
completedThis is the target state: credit contract between customer and Inbank has been activated, merchant is liable for the delivery of goods/services.
declinedCredit was declined by Inbank.
expiredThe session was not completed during the defined time period.

The integration flow can be configured to require a final merchant-side confirmation step, before the credit application process is completed. This is somewhat similar to the credit card flows where the amount is first reserved on the credit card account (transaction is approved), and is later 'captured' after the merchant has completed the transaction.

This may be handy if the stock is limited and the merchant does not allocate stock items before it is ensured that the customer can get the credit. If the merchant does not send the final approval (i.e. items are out of stock, order can not be completed), the granted credit is not completed.

Credit Contract State Model

Inbank will send callbacks about changes to the credit contract status. Contracts can have the following statuses:



StatusDescription

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.

activatedThis 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 unsigned or signed.

For the flow which includes merchant approval, signed contracts get the status cancelled when the merchant has not approved the contract.

terminatedAn existing credit contract has been terminated. This state can only be applied to contracts which previously were activated.

Callbacks

When initiating the payment session in Inbank Partner API the e-shop should provide 3 URLs:

  • redirect URL - the URL to which the customer's browser will be redirected back after the customer has completed the credit application dialog. Regardless of the outcome of the credit application process, the customer is redirected here, even if the credit is not granted.
  • cancel URL - the URL to which the customer's browser is redirected if the customer deliberately chooses to cancel the credit application dialog.
  • callback URL - the URL to which Inbank will send server-to-server callback notifications on session status change events.

Inbank will send two callbacks, both with the same structure and content:

  • First one is performed on redirect_url, via the customer's browser.
  • Second one is server-to-server callback which ensures that the merchant receives the callback. It is done on callback_url.

Note that the first callback may not arrive if the customer does not press the "back to merchant" button, or if there are connectivity or technical problems at the customer's device/browser. Thus there is no guarantee that the first callback will arrive, or which one of the two callbacks will arrive first. Callback requests are lightweight triggers for initiating activities on the merchant side. They contain only minimal information.

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 pos_session identifier either from the incoming message, or from the internal database as it was persisted when the session was initiated.
  • Inspect pos_session status and process the order payment status based on the pos_session state. If needed, you can also check the purchase reference.
  • 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

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

ParameterExample valueDescription
message%7B%22uuid%22%3A%22e4b5b81a-6d99-4a78-bd17-
46d19968eb7f%22%2C%22status%22%3A%22pending%22%2C%22
purchase_reference%22%3A%22Id+%231%22%7D		URL-encoded JSON structure containing information about the pos_session.

For more details, see the Callback message content chapter.

hmacc196e985640a6291723dc2717d264f82e70126c
34b107f3be5b22201cb147c98b9709f5184a7f2fe8268
4d6086eee07df8a46c28fc0edfdd14fd306579244664

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.

Callback Request Example

Request header

{"Content-Type":"application/x-www-form-urlencoded"}

Request body

message=%7B%22uuid%22%3A%223241a6d5-051b-415b-afc7-0a5aad115fcc%22%2C%22status%22%3A%22cancelled%22%2C%22
purchase_reference%22%3A%221234%22%7D&hmac=4c4686db2aac832dd2e001fdc02e2b4021dc5e49c064552215dab2ca9c564
9435562bc60e96b812ca8ea40223f500ced9c257541b43ab7fb482067c8bae7a963&timestamp=1553072069

Callback Message Content

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

  • uuid - POS session UUID.
  • status - status of the POS session at the moment of message dispatch. For more details, see the State model chapter.
  • purchase_reference - merchant side reference, i.e. order ID. For more details, see the Session initiation chapter.

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:

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);

API Requests

This section lists the API request required for the integration with the Inbank e-POS system. The enlisted API requests are used in the following way:

  1. The e-shop initiates a payment session using the POST /pos_sessions request. The response includes the uuid parameter which will then be used to link the credit application to the payment session. The redirect_url from the response indicates the link to which the client is to be redirected to complete the financing process.

    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.

  2. The e-shop submits the credit application containing the information about the purchase and the client using the POST /applications request. The submitted data will be used to make the decision on the possibility and conditions of the credit offer.

  3. The e-shop checks if the application has a decision from Inbank using the GET /applications request. As the decision process might take some time, the endpoint may need to be polled once a second for a maximum of 30 seconds. The response includes all the credit information necessary to display the offer to the customer..

  4. The e-shop redirects the client to Inbank's e-POS environment. Here customers are guided through a number of dialogs to complete the financing of the purchase. After the e-POS dialogs, customers are redirected back to the e-shop.

  5. The e-shop requests the details of the payment session to learn the identifier of the concluded contract, credit_contract_uuid, using the GET /pos_sessions request.

  6. The e-shop checks the status of the credit contract using the GET /contracts request. If the contract has status activated, the financing of the purchase has been successful.

Additionally, e-shops can provide approximate credit calculations on their sites using the POST /calculations request.

API Request Flow

The chart demonstrates the sequence in which the API requests should be applied to successfully initiate the payment session, redirect the customer to e-POS and later check the credit contract status to confirm that the financing has been successful.



Languages
Servers
Demo environment
https://demo-api.inbank.ee/
Live environment
https://api.inbank.ee/

Session Initiation

Request

POST /shops/:uuid/pos_sessions

Initiating the payment session is the first step of the financing process with Inbank. After the session is created it is possible to submit the credit application linking the UUID of the payment session to it.

Use POST /shops/:uuid/pos_session request to initiate a session. The response includes the identifier of the payment session - pos_session_uuid and the URL to which the customer is to be redirected - redirect_url.

For your convenience, we have listed the minimal data set which needs to be passed to Inbank.

Security
bearerAuth
Path
shop_uuidstringrequired
Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
Bodyapplication/jsonrequired
generalobject
customer_dataobject

Data used to pre-fill credit application fields regarding the customer.

customer_contact_dataobject

Data used to pre-fill credit application fields regarding customer contact information.

customer_address_dataobject

Data used to pre-fill credit application fields regarding customer address.

credit_application_dataobject

Credit application related attributes that a merchant can pass, and Inbank can use to pre-fill applications in e-POS.

user_ipstring

Customer browser IP address as seen by e-shop.

integration_infoobject

Information about the technical environment of the partner side integration, e.g. "ecom_platform":"string", "module":"string"

additional_dataobject

Container for additional data that e-shops can pass to e-POS dialogs (pre-filling forms).
Any keys are allowed.

originobjectrequired
origin.​valuestringrequired

Type of the integration method. Available option: redirect_integration

Value"redirect_integration"
purchaseobject
partner_urlsobject
curl -i -X POST \
  https://demo-api.inbank.ee/partner/v2/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/pos_sessions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_code": "product_code_here",
    "total_amount": 3000,
    "currency": "EUR",
    "locale": "et-ET",
    "partner_urls": {
      "return_url": "https://example.com/path/return",
      "cancel_url": "https://example.com/path/cancel",
      "callback_url": "https://example.com/path/callback"
    },
    "purchase": {
      "purchase_reference": "ORDER_000001",
      "merchant": {
        "merchant_domain_name": "wwww.example.com"
      }
    },
    "origin": {
      "value": "redirect_integration"
    }
  }'

Responses

Creates a new POS session

Bodyapplication/json
uuidstring

Identifier of the POS session. Store this identifier at the order metadata for later usage.

Example: "5e3a459a-aada-4d81-b6ad-09cb9483c8bf"
statusstring

The status of the POS session.

Example: "pending"
redirect_urlstring

The link to which the client is to be redirected to complete the financing process in the e-POS environment.

Example: "https://demo-epos.inbank.ee/session/5e3a459a-aada-4d81-b6ad-09cb9483c8bf"
Response
application/json
{
  "uuid": "5e3a459a-aada-4d81-b6ad-09cb9483c8bf",
  "status": "pending",
  "redirect_url": "https://demo-epos.inbank.ee/session/5e3a459a-aada-4d81-b6ad-09cb9483c8bf"
}

Credit Application Submission

Request

Once the e-shop receives a response to the payment session initiation request with the redirect URL and the UUID of the session, it can forward the data of the credit application to Inbank. To submit credit application data to Inbank, use the POST /partner/v2/shops/:shop_uuid/applications request.

Request payload consists of several sub-objects:

  • credit_application: monthly income, product code and other credit related data
  • customer: customer's identity code, name and gender
  • customer_contacts: customer's email and phone number
  • customer_identification: the type of customer identification document and its number
  • purchase: details about the purchased items

Important note for test environments

The phone number and email of one customer cannot be used for another customer. For testing purposes it means that if you introduce a new identity code, you should also generate a new document number, phone number and email address. If you use an existing customer's identity code, you can use both existing and new values for document number, phone number and email address. Due to banking secrecy we cannot indicate the exact reason behind the application failure (e.g. customer with such an email already exists) and will return a generic error: "Error has occurred, contact customer support".

Security
bearerAuth
Path
shop_uuidstringrequired
Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
Bodyapplication/jsonrequired
credit_applicationobject
customerobject
customer_addressesobject
customer_contactobject
customer_identificationobject
consentsobject
purchaseobject
curl -i -X POST \
  https://demo-api.inbank.ee/partner/v2/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/applications \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "credit_application": {
      "pos_session_uuid": "5e3a459a-aada-4d81-b6ad-09cb9483c8bf",
      "product_code": "example_product",
      "amount": "2400",
      "period": "12",
      "monthly_income": "2900",
      "monthly_financial_obligations": "100"
    },
    "customer": {
      "identity_code": "38808050001",
      "first_name": "John",
      "last_name": "Smith"
    },
    "customer_addresses": [
      {
        "street": "NIINE",
        "country": "EE",
        "zip_code": "10414"
      }
    ],
    "customer_contact": {
      "mobile": "+37253630000",
      "email": "test@test.com"
    },
    "customer_identification": {
      "document_type": "id_card",
      "document_number": "AA979080"
    },
    "consents": [
      {
        "type": "EMTA_REGISTRY_QUERY",
        "value": true,
        "text": "This is EMTA consent"
      }
    ]
  }'

Responses

Create a new application

Bodyapplication/json
uuidstring

Application uuid.

Example: "471e6282-3384-412b-af7b-646eb8f04391"
numbernumber(double)

Application reference number.

Example: 89002917439
statusstring

Session status.

Example: "pending"
product_codestring

Product code.

Example: "example_product"
amountnumber(double)

Financing amount.

Example: 1001
periodinteger(int32)

Financing period in months.

Example: 12
down_payment_amountnumber(double)

Down payment amount.

Example: 0
payment_dayinteger(int32)

Payment day.

Example: 15
start_datestring(date)

Start date.

Example: "2020-12-15"
end_datestring(date)

End date.

Example: "2021-11-15"
decision_statusstring

It can be considered that the application received a positive decision if its decision_status is positive. Usually, a new application has decision_status as pending until the decision is reached. To receive the application decision, the GET /application endpoint should be polled once a second for a maximum of 30 seconds.

Enum"positive""negative""manual_negative""failed""income_proof_requested""pending""manual"
Example: "positive"
decision_messagesstring

Contain a list of messages to be displayed to the customer on why the application decision received the corresponding status.

Example: "Positive decision"
changed_conditionsboolean

Annual credit cost rate.

Example: false
previous_uuidstring

Previous uuid.

Example: null
salesperson_referencestring

First name and last name of the sales person as it should appear on reports.

Example: "Earl James"
Response
application/json
{
  "uuid": "471e6282-3384-412b-af7b-646eb8f04391",
  "number": 89002917439,
  "status": "pending",
  "product_code": "example_product",
  "amount": 1001,
  "period": 12,
  "down_payment_amount": 0,
  "payment_day": 15,
  "start_date": "2020-12-15",
  "end_date": "2021-11-15",
  "decision_status": "positive",
  "decision_messages": "Positive decision",
  "changed_conditions": false,
  "previous_uuid": null,
  "salesperson_reference": "Earl James"
}

Application Details

Request

To check whether a credit application received a decision from Inbank and display the credit offer, the partner needs to get the data of the application and credit details using the GET /partner/v2/shops/:shop_uuid/applications/:application_uuid request.

The response includes the decision_status parameter which can have one of the following values: pending, positive, manual_negative, income_proof_required, negative, failed. It can be considered that the application received a positive decision from Inbank if its decision_status is positive. Once the partner receives a positive credit decision from Inbank, it can display the offer to the customer.

As the decision process might take some time, the endpoint may need to be polled once a second for a maximum of 30 seconds.

Note that there are situations when the application data may be altered by Inbank systems during processing, in that case the application is also assigned a new UUID and the returned application data contains the attribute changed_conditions with value true. The changed_conditions attribute informs you if the application has undergone changes or not. If you persist Inbank application UUID in your system - you should always compare the returned UUID with the one you requested and update the UUID on your side respectively.

Security
bearerAuth
Path
shop_uuidstringrequired
Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
application_uuidstringrequired
Example: 471e6282-3384-412b-af7b-646eb8f04391
Query
typestring
Default "latest"
Enum"latest""initial""exact"
curl -i -X GET \
  'https://demo-api.inbank.ee/partner/v2/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/applications/471e6282-3384-412b-af7b-646eb8f04391?type=latest' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Return application details by shop UUID & application UUID

Bodyapplication/json
productobject
shopobject
credit_applicationobject
purchasestring

Purchase.

Example: null
contractstring

Contract.

Example: null
payment_scheduleobject
Response
application/json
{
  "product": {
    "code": "example_product9",
    "name": "Hire-purchase",
    "subtype": "hire_purchase",
    "type": "loan"
  },
  "shop": {
    "name": "Online testshop",
    "type": "online_partner",
    "uuid": "a93f1f44-d5dd-4469-bfcc-c1de9e969213"
  },
  "credit_application": {
    "uuid": "471e6282-3384-412b-af7b-646eb8f04391",
    "number": "89002917222",
    "credit_application_status": "pre_request",
    "offer_valid_to": "2020-11-15",
    "created_at": "2020-11-05T13:01:42+02:00",
    "creator_name": null,
    "process_status": "offer",
    "down_payment_amount_total": "0.0",
    "salesperson_reference": "Earl James",
    "period": 12,
    "amount": "1001.0",
    "payment_day": 15,
    "max_limit": "3000.0",
    "decision_status": "positive",
    "decision_messages": [ … ],
    "down_payment_amount_prc": null,
    "income_source": null,
    "civil_status": null,
    "housing_status": null,
    "monthly_income": "2900.0",
    "monthly_household_costs": 0,
    "monthly_financial_obligations": 0,
    "employer_name": null,
    "employer_registry_code": null,
    "employer_phone": null,
    "employment_start_year": null,
    "employment_start_month": null,
    "employment_end_year": null,
    "employment_end_month": null,
    "dependants_count": 0,
    "dependants_over_18": null,
    "changed_conditions": false,
    "previous_uuid": null,
    "confirmed_at": "2020-11-05T13:01:42+02:00"
  },
  "purchase": null,
  "contract": null,
  "payment_schedule": {
    "period": 12,
    "amount": "1001.0",
    "contract_fee_amount_total": "11.0",
    "contract_fee_prc": "0.011",
    "contract_fee_type": "is_paid_according_to_repayment_schedule",
    "credit_cost_amount_total": "157.84",
    "credit_cost_rate_annual": "0.301",
    "first_payment_amount": "96.57",
    "first_payment_date": "2020-12-15",
    "interest_rate_annual": "0.149",
    "last_payment_amount": "96.57",
    "last_payment_date": "2021-11-15",
    "net_credit_amount": "1001.0",
    "payment_amount_monthly": "96.57",
    "repayments_amount_total": "1158.84",
    "down_payment_main_part": "0.0",
    "down_payment_amount_total": "0.0",
    "admin_fee_amount_monthly": "0.0",
    "admin_fee_amount_total": "0.0",
    "insurance_fee_amount_total": "0.0",
    "residual_amount_total": "0.0",
    "residual_amount_prc": "0.0",
    "interest_bearing_amount": "1001.0",
    "interest_amount_total": "146.84",
    "payment_day": 15
  }
}

Payment Session Details

Request

To check that the payment session has been concluded successfully and the purchase has been financed, the partner needs to check the details of the payment session and credit contract. Information about the payment session can be retrieved using the GET /partner/v2/shops/:shop_uuid/pos_sessions/:session_uuid request.

The response includes the credit_contract_uuid parameter which will then be used to check the status of the credit contract.

Security
bearerAuth
Path
shop_uuidstringrequired
Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
pos_session_uuidstringrequired
Example: 5e3a459a-aada-4d81-b6ad-09cb9483c8bf
curl -i -X GET \
  https://demo-api.inbank.ee/partner/v2/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/pos_sessions/5e3a459a-aada-4d81-b6ad-09cb9483c8bf \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Return POS session details

Bodyapplication/json
uuidstring

Pos session uuid. E.g. 5e3a459a-aada-4d81-b6ad-09cb9483c8bf

product_codestring

E.g. loan

total_amountnumber(double)

E.g. 9000

currencystring

E.g. EUR

statusstring

Credit contract status. E.g. pending

salesperson_referencestring
Example: "E.g. `REF120`"
localestring
Example: "E.g. `et-ET`"
user_ipstring

E.g. 192.128.00.01

partner_urlsobject

Partnern urls.

customer_dataobject

Data used to pre-fill credit application fields regarding the customer.

customer_contact_dataobject

Data used to pre-fill credit application fields regarding customer contact information.

customer_address_dataobject

Data used to pre-fill credit application fields regarding customer address.

credit_application_dataobject

Credit application related attributes that a merchant can pass, and Inbank can use to pre-fill applications in e-POS.

integration_infoobject

Information about the technical environment of the partner side integration.

additional_datastring

E.g. key1

purchaseobject
created_atstring(date-time)

E.g. 2020-03-04T12:46:06+01:00

valid_untilstring(date-time)

E.g. 2020-03-11T12:46:06+01:00

credit_application_uuidstring

E.g. 471e6282-3384-412b-af7b-646eb8f04391

credit_contract_uuidstring

E.g. 788ec8c4-c497-470b-8505-2303f151d427

Response
application/json
{
  "uuid": "5e3a459a-aada-4d81-b6ad-09cb9483c8bf",
  "product_code": "loan",
  "total_amount": 9000,
  "currency": "EUR",
  "status": "pending",
  "salesperson_reference": "Earl James",
  "locale": "et-ET",
  "user_ip": "192.128.00.01",
  "partner_urls": {
    "return_url": "https://campaign.inbank.ee/tmp/post.php?type=return",
    "cancel_url": "https://campaign.inbank.ee/tmp/post.php?type=cancel",
    "callback_url": "https://campaign.inbank.ee/tmp/post.php?type=callback"
  },
  "customer_data": {
    "identity_code": "39108190000",
    "first_name": "John",
    "last_name": "Smith",
    "gender": "M"
  },
  "customer_contact_data": {
    "email": "john.smith@session.pos",
    "mobile": "51231412",
    "phone": "6123123"
  },
  "customer_address_data": {
    "type": "legal",
    "street": "NIINE",
    "country": "EE",
    "county": "HARJU MAAKOND",
    "city": "TALLINN",
    "zip_code": "10414",
    "house": "11",
    "township": "HARJU"
  },
  "credit_application_data": {
    "number": "8000000123",
    "salesperson_reference": "Earl James"
  },
  "integration_info": {
    "ecom_platform": "magento",
    "module": "inbank-2.1.0",
    "extra_key_3": "#3"
  },
  "additional_data": {
    "key_1": "key1"
  },
  "purchase": {
    "purchase_reference": "ORDER_000001",
    "description": "Description of ORDER_000001 order",
    "additional_details": { … },
    "items": [ … ],
    "created_at": "2020-03-04T12:46:06+01:00"
  },
  "created_at": "2020-03-04T12:46:06+01:00",
  "valid_until": "2020-03-11T12:46:06+01:00",
  "credit_application_uuid": "471e6282-3384-412b-af7b-646eb8f04391",
  "credit_contract_uuid": "788ec8c4-c497-470b-8505-2303f151d427"
}

Contract Details

Request

Note that this request should not be used if you are integrating with the Indivy - pay next month payment product.

GET /partner/v2/shops/:shop_uuid/contracts/:contract_uuid

Once the credit contract UUID has been retrieved via the GET /pos_sessions request, the e-shop can check the status of the credit contract using the GET /partner/v2/shops/:shop_uuid/contracts/:contract_uuid request. The response will include the status parameter. If the status is activated, the purchase has been successfully financed by Inbank and the purchase items can be forwarded to the customer.

Security
bearerAuth
Path
shop_uuidstringrequired
Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contract_uuidstringrequired
Example: 788ec8c4-c497-470b-8505-2303f151d427
curl -i -X GET \
  https://demo-api.inbank.ee/partner/v2/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/contracts/788ec8c4-c497-470b-8505-2303f151d427 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Returns contract details

Bodyapplication/json
statusstring

Contract status.

termination_reasonstring

Contract termination reason type.

activated_atstring

Contract activated at.

activator_namestring

Contract activator name.

consolidation_loansstring

List of loans.

credit_application_contract_reference_uuidstring

Credit Application Contract reference UUID.

customer_signedstring(date-time)

Customer signed at.

partner_approval_atstring(date-time)

Partner approval at.

payout_bank_accountstring

Payout bank account.

process_statusstring

Credit application process status.

product_codestring

Product code.

numberstring

Contract number.

rep_signedstring(date-time)

Rep signed at.

repayment_ibanstring

Repayment iban.

signed_atstring(date-time)

Signed at.

terminated_atstring

Contract terminated at.

uuidstring

Contract UUID.

withdrawableboolean

If contract is withdrawable.

customer_uuidstring

Contract customer UUID.

identification_satisfiedboolean

Customer identification acceptance status for contract.

Response
application/json
{
  "contract": {
    "status": "activated",
    "termination_reason": null,
    "activated_at": "2022-07-01T10:06:36.313+03:00",
    "activator_name": null,
    "credit_application_contract_reference_uuid": "f02e3cf9-8228-4234-b9aa-fb07768500c5",
    "customer_signed": "2022-07-01T10:06:32+03:00",
    "partner_approval_at": null,
    "payout_bank_account": "EE382200221020145685",
    "process_status": "activated",
    "product_code": "product_code_here",
    "number": "89003022608",
    "rep_signed": "2022-07-01T10:06:32+03:00",
    "signed_at": "2022-07-01T10:06:32+03:00",
    "terminated_at": null,
    "uuid": "788ec8c4-c497-470b-8505-2303f151d427",
    "withdrawable": true,
    "customer_uuid": "fac6e447-aa40-48ec-a65d-a4acb24eceb6",
    "identification_satisfied": true
  }
}

Calculator

Request

POST /shops/:uuid/calculations

To get a credit calculation from Inbank, use the POST /shops/:uuid/calculations request.

Note that this request returns the preliminary non-personalized credit conditions. The final conditions will be presented after the customer submits a credit application and receives a positive decision.

Security
bearerAuth
Path
shop_uuidstringrequired
Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
Bodyapplication/jsonrequired
product_codestringrequired

Reference to product code.

Example: "product_code_here"
amountnumber(double)required

Total financing amount. If down payment is used, then the amount includes the down payment amount. Minimum and maximum amount depends on product setup.

Example: 2000
periodintegerrequired

Number of months for repayments; allowed values depend on product setup.

Example: 12
payment_dayinteger

Payment day.

Example: 5
down_payment_amountnumber(double)

Down payment amount.

Example: 0
currencystring(double)

Currency code in uppercase. For example:

  • EUR
  • PLN
  • CZK
Example: "EUR"
response_levelstring

Indication of how detailed the returned response should be. It is recommended to use the minimum response level that is needed for a specific calculation, e.g. if only monthly payment is needed, then use simple.

Default "simple"
Enum"simple""advanced""payment_schedule"
Example: "simple"
curl -i -X POST \
  https://demo-api.inbank.ee/partner/v2/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/calculations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_code": "product_code_here",
    "amount": 2000,
    "period": 12,
    "payment_day": 5,
    "down_payment_amount": 0,
    "currency": "EUR",
    "response_level": "simple"
  }'

Responses

Creates a new calculation

Bodyapplication/json
product_codestring

Product code.

Example: "product_code_here"
amountnumber(double)

Loan amount.

Example: 200.99
periodinteger(int32)

Loan period.

down_payment_amountnumber(double)

Down payment amount.

payment_dayinteger(int32)

Payment day.

response_levelstring

Response level.

Example: "simple"
currencystring

Currency.

Example: "EUR"
payment_amount_monthlynumber(double)

Monthly payment.

interest_rate_annualnumber(double)

Annual interest rate.

credit_cost_rate_annualnumber(double)

Annual credit cost rate.

total_costnumber(double)

Total cost.

total_cost_of_creditnumber(double)

Total cost of credit.

down_payment_minimum_percentagenumber(double)

Down payment minimum percentage.

down_payment_minimum_amountnumber(double)

Down payment minimum amount.

advancedobject
payment_scheduleArray of objects(paymentSchedule)

Payment schedule items.

Response
application/json
{
  "product_code": "product_code_here",
  "amount": 1300,
  "period": 6,
  "down_payment_amount": 0,
  "payment_day": 5,
  "response_level": "simple",
  "currency": "EUR",
  "payment_amount_monthly": 348.79,
  "interest_rate_annual": 0.1,
  "credit_cost_rate_annual": 0.1608,
  "total_cost": 2092.74,
  "total_cost_of_credit": 92.74,
  "down_payment_minimum_percentage": 0,
  "down_payment_minimum_amount": 0
}