Direct API Guide

Documentation version 2.02, 25.11.2022

Please note, that the given document is only applicable for partners integrating in Estonia.

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.

If you have any questions regarding Inbank API or have trouble with your integration, just contact integration@inbank.ee and we will be happy to help.

Note, per the contract between the partner and Inbank, 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:

Inbank 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.

Indivy Pay in parts

The Indivy Pay in parts payment solution offers clients to buy goods and services and pay for them later in several equal instalments. Indivy Pay in parts is free of charge for customers, while merchants get paid upfront in full the next working day. Read more about Indivy Pay in parts on our website.

Flow Overview

URLs

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/

API Request Flows in Case of Positive Decision

API Request Flow

*Note that step 6 is only required if the flow is using SMS signing.

API Request Flow with Partner Approval

*Note that step 6 is only required if the flow is using SMS signing.

API Request Flow with Down Payment

API Request Flow with Down Payment and Partner Approval

API Request Flows in Case of income_proof_required Decision

* 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.

API Request Flow

API Request Flow with Partner Approval

API Request Flow with Down Payment

API Request Flow with Down Payment and Partner Approval

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.ee

For testing purposes, the system returns preconfigured decisions. Positive decisions are given for amounts 0 - 500, 1001 - 3000, 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 Indivy Pay in parts payment product, the SMS message is hardcoded to value 0000.

To test the financing products in Estonia, you can safely use your own Estonian ID-code and ID-card, as the demo environment does not initiate real binding contracts. Alternatively, 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.

Credit Contract State Model

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 `unsigned` or `signed`. For the flow which includes merchant approval, `signed` contracts get the status `cancelled` when the merchant has not approved the contract.
terminated	An existing credit contract has been terminated. This state can only be applied to contracts which previously were `activated`.

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:

{
    "error": [
        "unauthorized"
    ]
}

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

API Endpoints

The API endpoints cover all the functionality necessary for full integration with Inbank systems.

Calculations

Monthly Payment Calculations

POST /partner/v2/shops/:shop_uuid/calculations

The calculations endpoint retrieves a preliminary calculation based on the credit amount and period. The actual calculation will be presented to the client after there is a decision based on the credit application.

SecuritybearerAuth

Request

path Parameters

shop_uuid

required

string

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

Request Body schema: application/json

product_code required	string Product code.
amount required	number <double> Financing amount.
period required	integer Financing period in months. Options depend on the particular product.
down_payment_amount	number <double> Down payment amount. If not provided, then set to `0`.
payment_day	integer Payment day. If not indicated, the default payment day set for this product will be used.
response_level	string Default: "simple" Indication of how detailed the returned response should be. If not selected, the simple option will be used by default. Note, that to show the Indivy Pay in parts payments, you need to use the `payment_schedule` response level. Enum: "simple" "advanced" "payment_schedule"

Responses

201

Creates a new calculation

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/calculations

Request samples

Payload
curl
Node.js
Python

application/json

{"product_code": "product_code_here",
"amount": 2000,
"period": 12,
"down_payment_amount": 0,
"payment_day": 5,
"response_level": "simple"
}

Response samples

application/json

{"product_code": "product_code_here",
"amount": 2000,
"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
}

Credit Applications

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.

Credit Application Submission

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.

POST /partner/v2/shops/:shop_uuid/applications

A credit application is submitted using the POST /partner/v2/:shop_uuid/applications endpoint. The credit application contains the credit period and amount, identification data and other information regarding the customer and the purchase.

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_contact: customer's email and phone number
customer_addresses: customer's address details
customer_identification: the type of customer identification document and its number
consents: customer's consent for processing of their data
purchase: details about the purchased items

Important note for test environments

Document number, 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".

The decision_status parameter can have the following values: positive, negative, manual_negative, failed, income_proof_required, pending, manual. 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.

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

If the response includes the income_proof_required decision status, the customer needs to submit their income proof documents to Inbank.

The new income_proof_type parameter in the response to POST /applications indicates the manner in which the documents need to be submitted, either via the AIS upload process or the manual upload, or via a manual upload only. Possible values are:

ais_with_fallback_manual_upload_option - the customer can submit their income proof statement via AIS upload process or manual upload. To perform the AIS upload process, you need to redirect the customer to a third party URL. After the AIS upload process is complete, the customer will be redirected back to the flow on your site.
manual_internal_verification - the customer can submit their income proof statement via the manual upload only.

Please note that after the AIS upload process, the application might once again receive the income_proof_required decision status with the manual_internal_verification verification type in cases when Inbank needs additional data from the customer to make a decision.

SecuritybearerAuth

Request

path Parameters

shop_uuid

required

string

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

Request Body schema: application/json

	object
	object
	object
	object
	object
	object
	object

Responses

201

Create a new application

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/applications

Request samples

Payload
curl
Node.js
Python

application/json

{"credit_application": {"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"
}
]
}

Response samples

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": null
}

AIS Bank List Retrieval

GET /partner/v2/shops/:shop_uuid/account_statements/bank_list?application_uuid=application_uuid

In cases when the application receives the income_proof_required decision, the flow needs to include the AIS upload process. The first step is retrieving the list of available banks from which the account statement can be provided via the GET /partner/v2/shops/:shop_uuid/account_statements/bank_list API request. The request returns the name, ID and icon URL for each of the available banks. The selection of the banks needs to be displayed to the customer.

Please note that the selection of banks is subject to change.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
application_uuid required	string The application for which the AIS upload is being initiated. The credit application UUID is included in the response to the `POST /application` request which submits the credit application to Inbank. Example: 471e6282-3384-412b-af7b-646eb8f04391

Responses

200

Return bank list by shop UUID & application UUID

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

get/partner/v2/shops/{shop_uuid}/account_statements/bank_list/{application_uuid}

Request samples

curl
Node.js
Python

Response samples

application/json

{"bank_list": [{"name": "Citadele",
"id": "CITADELE_PARXEE22",
"icon_url": "https://cdn.nordigen.com/ais/CITADELE.png"
},
{"name": "Coop Pank",
"id": "COOP_EKRDEE22",
"icon_url": "https://cdn.nordigen.com/ais/COOP.png"
},
{"name": "Sandbox",
"id": "SANDBOXFINANCE_SFIN0000",
"icon_url": "https://cdn.nordigen.com/ais/SANDBOX.png"
}
]
}

AIS Upload Session Initiation

POST /partner/v2/shops/:shop_uuid/account_statements/initiate_retrieval

Once the customer selects a bank, the AIS upload session can be started using the POST /api/partner/v2/shops/:shop_uuid/account_statements/initiate_retrieval API request. The response includes the redirect URL to which the customer should be forwarded to complete the AIS upload process. Once that process is complete, the customer will be redirected back to your site, to the return URL you have indicated in the request body.

To learn the new decision which the application has received after the AIS upload and processing, the GET /partner/v2/shops/:shop_uuid/applications/:application_uuid endpoint needs to be polled until there is a new decision_status. The usual processing time is within 1 working day.

SecuritybearerAuth

Request

path Parameters

shop_uuid

required

string

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

Request Body schema: application/json

application_uuid required	string The application for which the AIS upload session is being started. The credit application UUID is included in the response to the `POST /application` request which submits the credit application to Inbank.
return_url required	string The URL to which the customer should be redirected back after the AIS upload process is complete.
bank_id required	string The ID of the bank selected by the customer for the AIS upload process. The IDs are included in the response to the `GET /account_statements/bank_list` request.
locale required	string The locale which will be used in the AIS upload process. Available options: et, lv, lt, pl, cz, ru.

Responses

201

Upload session

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/account_statements/initiate_retrieval

Request samples

Payload
curl
Node.js
Python

application/json

{"application_uuid": "42c939bc-1111-2222-3333-b84fea5b86f6",
"return_url": "https://test.com",
"bank_id": 24,
"locale": "en"
}

Response samples

application/json

{"retrieval_id": "b7cfdbc3-1111-2222-3333-6c42b60129b8",
"redirect_url": "https://ob.nordigen.com/psd2/start/1e2d261a2d9d/SWEDBANK"
}

Manual Account Statement Upload

POST /partner/v2/shops/:shop_uuid/applications/:application_uuid/attachments

The account statement file can be forwarded to Inbank via the POST /partner/v2/shops/:shop_uuid/applications/:application_uuid/attachments endpoint. If applied, this endpoint needs to be used instead of the AIS upload related endpoints (steps 2 and 3 of the API request flows).

Please note, as income proof documents are processed by Inbank representatives in case of a manual upload, income verification can take some time. To learn the new decision the application has received after the account statement upload and processing, the GET /partner/v2/shops/:shop_uuid/applications/:application_uuid endpoint needs to be polled until there is a new decision_status.

Request body parameters:

Attachments must be submitted as form-data.
cURL example: --form "attachments[]=@/path_to/file1.pdf" --form "attachments[]=@/path_to/file2.pdf"

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
application_uuid required	string The unique identifier of the application. Example: 471e6282-3384-412b-af7b-646eb8f04391

Request Body schema: application/json

attachments required	Array of arrays Files to be added as attachments.
type required	string Type of document. Available option: `income_proof_document`. Value: "income_proof_document"
description required	string Additional description of the attachments.

Responses

204

Upload session

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/applications/{application_uuid}/attachments

Request samples

Payload
curl
Node.js
Python

application/json

{"attachments": [ ],
"type": "income_proof_document",
"description": "Description here"
}

Response samples

application/json

{"message": "unauthorized"
}

Application Details

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.

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 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.

If the response includes the income_proof_required decision status, the customer needs to submit their income proof documents to Inbank. The income_proof_type parameter in the response indicates the manner in which the documents need to be submitted, either via the AIS upload process or the manual upload, or via a manual upload only. Possible values are:

ais_with_fallback_manual_upload_option - the customer can submit their income proof statement via AIS upload process or manual upload. To perform the AIS upload process, you need to redirect the customer to a third party URL. After the AIS upload process is complete, the customer will be redirected back to the flow on your site.
manual_internal_verification - the customer can submit their income proof statement via the manual upload only.

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 conditions_changed with value true. The conditions_changed 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.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
application_uuid required	string The unique identifier of the application. Example: 471e6282-3384-412b-af7b-646eb8f04391

query Parameters

type	string Default: "latest" Enum: "latest" "initial" "exact"

Responses

200

Return application details by shop UUID & application UUID

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

get/partner/v2/shops/{shop_uuid}/applications/{application_uuid}

Request samples

curl
Node.js
Python

Response samples

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": null,
"period": 12,
"amount": "1001.0",
"payment_day": 15,
"max_limit": "3000.0",
"decision_status": "positive",
"decision_messages": ["Positive decision"
],
"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
}
}

Application Approval

POST /partner/v2/shops/:shop_uuid/applications/:application_uuid/accept

After the credit application receives a positive decision and the credit offer is presented to the customer, they can choose to accept the offer, which is done through the POST /partner/v2/shops/:shop_uuid/applications/:application_uuid/accept endpoint. Accepting the application automatically creates a contract and returns the identifier of the contract in the response.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
application_uuid required	string The unique identifier of the application. Example: 471e6282-3384-412b-af7b-646eb8f04391

Responses

201

Accepts application and creates contract

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/applications/{application_uuid}/accept

Request samples

curl
Node.js
Python

Response samples

application/json

{"contract": {"uuid": "5e3a459a-aada-4d81-b6ad-09cb9483c8bf"
}
}

Application Cancellation

POST /partner/v2/shops/:shop_uuid/applications/:application_uuid/cancel

After the credit application receives a positive decision and the credit offer is presented to the customer, they can choose to cancel their credit application, which is done through the POST /partner/v2/shops/:shop_uuid/applications/:application_uuid/cancel endpoint.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
application_uuid required	string The unique identifier of the application. Example: 471e6282-3384-412b-af7b-646eb8f04391

Responses

204

Cancel application

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/applications/{application_uuid}/cancel

Request samples

curl
Node.js
Python

Response samples

application/json

{"message": "unauthorized"
}

Credit Contracts

Credit contracts contain the details of the financing agreement between the customer and Inbank. Once the contract is activated, the partner is to supply goods/services to the customer.

Contract Printout

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

The details of the contract are included in the printout which can be retrieved using the GET /partner/v2/shops/:shop_uuid/contracts/:contract_uuid/printouts endpoint. The response includes the link to the contract printout file.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contract_uuid required	string The unique identifier of the contract. Example: 788ec8c4-c497-470b-8505-2303f151d427

query Parameters

force_regeneration

boolean

Whether or not the resulting printout should be regenerated. Printout regeneration is required for cases when certain data is added to the contract after it is initially formed (e.g. purchase details). Force regeneration ensures that the contract printout includes all the new contract related data available in the system.

Responses

200

Gets contract printout

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

get/partner/v2/shops/{shop_uuid}/contracts/{contract_uuid}/printouts

Request samples

curl
Node.js
Python

Response samples

application/json

{"uuid": "8a5951fb-835f-4f5f-ae1a-508d5bdd15d5",
"link": "https://test.link.com/attachments/printout/contract_89002917222"
}

Contract Signing

POST /partner/v2/shops/:shop_uuid/contracts/:contract_uuid/signings

After the customer accepts the credit offer and has reviewed the contract, they can proceed to contract signing which is done via the POST /partner/v2/shops/:shop_uuid/contracts/:contract_uuid/signings endpoint. There are the following signing methods available:

redirect - the method is used for contract signing by redirecting the client to a separate environment. The response to this request returns the URL to which the client should be redirected. The signing environment can be built into your site as an iFrame or just opened in a new browser tab. This signing method is available for the Inbank Hire Purchase payment product.
digital - the method is used in cases when the partner has a separate signing solution. The request with the digital signing method is used as a confirmation that signing has been successful. This signing method is available for the Inbank Hire Purchase payment product.
paper - the method is used if you are collecting paper contracts signed by the customer. This signing method is available for Indivy Pay in parts and Inbank Hire Purchase payment products.
sms - with this method the signing is done using an SMS code. After you send the request, the customer will receive an SMS with the code from Inbank. After that, the code is sent over to Inbank for confirmation via the PATCH /contracts/:contract_uuid/signings request. This signing method is available for the Indivy Pay in parts payment product.
send_to_signing_sms and send_to_signing_email methods send a link to the Inbank environment where customers can sign the contract. The link is sent to the mobile number / email address which was indicated in the credit application. This signing method is available for the Inbank Hire Purchase payment product.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contract_uuid required	string The unique identifier of the contract. Example: 788ec8c4-c497-470b-8505-2303f151d427

Request Body schema: application/json

method

required

string

The signing method to be used.

Enum: "paper" "digital" "sms" "sms_nexmo" "redirect" "payment" "send_to_signing_email" "send_to_signing_sms"

Responses

201

Creates a new signing

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/contracts/{contract_uuid}/signings

Request samples

Payload
curl
Node.js
Python

application/json

{"method": "redirect"
}

Response samples

application/json

{"contract": {"uuid": "6b9fd89c-ddbd-4e27-9291-3de50d000000",
"number": 89003110000,
"customer_signed": null,
"redirect_url": "https://gateway-sandbox.dokobit.com/signing/e1a14498554d876"
}
}

Down Payment Link Retrieval

POST /partner/v2/shops/:shop_uuid/contracts/:contract_uuid/payment_link

The down payment transfer is done via a redirect to the payment system. The link to the payment system can be retrieved via POST /payment_link. The link to which the customer is to be redirected is in the response to the request, redirect_url parameter. After the transfer is done, the customer is redirected back to the URL the partner indicates in the body of the request.

As the next step, the customer is to be redirected to the payment system (redirect_url from the response) to complete the down payment transfer.

The return URL sent in the body of the request should end with a status variable, for example - "return_url": "https://inbank.ee/session/:uuid/downpayment?status={status}". When redirecting the customer back, the payment system will fill that variable with one of the following values:

SUCCESS - the down payment has been made and the contract will be activated. If the flow includes partner approval, the partner can now approve the contract and the contract will then be activated.
FAILED - the down payment was not successful. The page the customer is redirected to can prompt to attempt the down payment once more. Note that initiating a new payment via POST /payment_link is needed for each attempt to make a down payment.
UNKNOWN - the status of the down payment is unconfirmed at the moment. In this case the down payment can yet succeed or fail. The page the customer is redirected to can inform that the down payment is yet to be verified.

In case of the UNKNOWN status, the partner system needs to check at reasonable intervals if the down payment has been confirmed. This can be done using the GET /contracts/:contract_uuid API request. The response to this API request will contain the process_status parameter:

Until the down payment is confirmed, the process_status will remain in waiting_for_downpayment. Note that if the contract remains in the process_status of waiting_for_downpayment after the redirect with status UNKNOWN for more than 24 hours, we recommend contacting either Inbank or the customer.
Once the down payment has been confirmed, the process_status will change to activated, or waiting_for_partner_confirmation if the flow includes partner approval.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contract_uuid required	string The unique identifier of the contract. Example: 788ec8c4-c497-470b-8505-2303f151d427

Request Body schema: application/json

return_url

required

string

The URL to which the customer is to be redirected back after the down payment transfer.

Responses

201

Create payment link for contract

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/contracts/{contract_uuid}/payment_link

Request samples

Payload
curl
Node.js
Python

application/json

{"return_url": "https://inbank.ee/session/:uuid/downpayment?status={status}"
}

Response samples

application/json

{"redirect_url": "https://igw-demo.every-pay.com/lp/zag/N2y",
"payment_methods": [{"display_name": "Luminor Bank AS; ema",
"redirect_url": "https://igw-demo.every-pay.com/lp/id6/wfS?method_source=luminor",
"logo_url": "https://igw-demo.every-pay.com/assets/payment_methods/luminor-028.svg"
},
{"display_name": "Luminor Bank AS; ema",
"redirect_url": "https://igw-demo.every-pay.com/lp/id6/wfS?method_source=luminor",
"logo_url": "https://igw-demo.every-pay.com/assets/payment_methods/luminor-028.svg"
},
{"display_name": "Luminor Bank AS; ema",
"redirect_url": "https://igw-demo.every-pay.com/lp/id6/wfS?method_source=luminor",
"logo_url": "https://igw-demo.every-pay.com/assets/payment_methods/luminor-028.svg"
}
]
}

Contract Merchant Approval

POST /partner/v2/shops/:shop_uuid/contracts/:contract_uuid/merchant_approval

If the flow includes merchant approval, the merchant checks if the status of the contract is signed using the GET /partner/v2/shops/:shop_uuid/contracts/:contract_uuid request. When the contract is in the signed status, the merchant needs to approve or cancel the contract. As processing customer signing might take some time, the endpoint may need to be polled once every second for a maximum of 15 seconds.

To approve the contract, the e-shop needs to know the credit contract UUID, which is in the response to the POST/:application_uuid/accept request.

The request does not require any parameters to be passed in its body.

Note that you can also approve contracts in the Partner Portal.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contract_uuid required	string The unique identifier of the contract. Example: 788ec8c4-c497-470b-8505-2303f151d427

Responses

204

Merchant approval and activation

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/contracts/{contract_uuid}/merchant_approval

Request samples

curl
Node.js
Python

Response samples

application/json

{"message": "unauthorized"
}

Contract Cancellation

POST /partner/v2/shops/:shop_uuid/contracts/:contract_uuid/cancel

To cancel the contract, the e-shop needs to know the credit contract UUID, which is in the response to the POST/:application_uuid/accept request.

The request does not require any parameters to be passed in its body.

Note that you can also cancel contracts in the Partner Portal.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contract_uuid required	string The unique identifier of the contract. Example: 788ec8c4-c497-470b-8505-2303f151d427

Responses

204

Cancel contract

401

Unauthorized

403

Forbidden

404

Not Found

422

Unprocessable Entity

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/contracts/{contract_uuid}/cancel

Request samples

curl
Node.js
Python

Response samples

application/json

{"message": "unauthorized"
}

Contract Status

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

Once the credit contract UUID has been retrieved and the contract has been signed, the partner 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.

If the flow includes merchant approval, the merchant checks if the status of the contract is signed. When the contract is in the signed status, the merchant needs to approve or cancel the contract. If the merchant approved the contract, they need to check if the contract status has been changed to activated, which indicates that the purchase was successfully financed by Inbank.

For the flow which is to include down payment transfer, the contract status needs to be checked twice as well:

Firstly, after contract signing, the partner checks that the status of the contract is signed to see if the signing process has been completed.
Secondly, after the POST /payment_link API call, the partner checks the status of the contract to make sure the down payment transfer has been successful. If the status is activated, the purchase has been successfully financed by Inbank and the purchase items can be forwarded to the customer.

As customer signing processing might take some time, the endpoint may need to be polled for a certain amount of time:

In case of digital, sms or paper signing methods, the endpoint needs to be polled once every second for a maximum of 15 seconds.
In case of the redirect, send_to_signing_sms and send_to_signing_email signing methods, there is no certain time when the customer will perform the signing. In this case, the endpoint needs to be polled at a reasonable interval for 7 days. This is also applicable if the flow includes the income proof verification process. For detailed information on the income proof flow, please contact your Inbank representative.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contract_uuid required	string The unique identifier of the contract. Example: 788ec8c4-c497-470b-8505-2303f151d427

Responses

200

Returns contract details

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

get/partner/v2/shops/{shop_uuid}/contracts/{contract_uuid}

Request samples

curl
Node.js
Python

Response samples

application/json

{"contract": {"status": "unsigned",
"termination_reason": null,
"uuid": "11d1baeb-1da1-1c01-b111-12111211c1a1",
"number": 89001350000,
"payout_account_number": "EE19824845453792774580000000",
"activated_at": null,
"activator_name": null,
"terminated_at": null,
"product_code": "insurance_fin",
"customer_signed": null,
"rep_signed": null,
"signed_at": null,
"partner_approval_at": null,
"customer_uuid": "40837f6d-0000-0000-0000-59a5b1efedd8",
"identification_satisfied": true
}
}

Contract Withdrawal

POST /partner/v2/shops/:shop_uuid/contracts/:contract_uuid/merchant_withdrawal

Using this endpoint, information on Inbank Hire Purchase and Indivy Pay in parts purchase returns can be submitted to Inbank.

This API call notifies Inbank that the merchant is willing to make withdrawal of the indicated contract. The exact terms of withdrawal need to be agreed with Inbank.

SecuritybearerAuth

Request

path Parameters

shop_uuid required	string The unique identifier of the shop. Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213
contract_uuid required	string The unique identifier of the contract. Example: 788ec8c4-c497-470b-8505-2303f151d427

Responses

201

Merchant withdrawal

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

post/partner/v2/shops/{shop_uuid}/contracts/{contract_uuid}/merchant_withdrawal

Request samples

curl
Node.js
Python

Response samples

application/json

{"message": "unauthorized"
}