Request Structure

Integration Guide for Inbank Smart Rent
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

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

Documentation version 3.04, 16.01.2025

Introduction

Here at Inbank, we strive to help our partners sell more by simplifying purchases and making financing more accessible to customers.

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

For any questions regarding the integration process, contact Inbank at:

Flow Overview

In general, the flow looks like this:

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

Inbank will provide you with everything you need to start using our Partner API. This includes the necessary keys, product configuration, etc. For any questions regarding the integration process, contact Inbank at:

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 the 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 later on.

For testing purposes, the demo environment returns preconfigured decisions:

positive decisions are given for amounts 0 - 500, 1426 - ...
negative decisions are given for amounts 1001- 1100.

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:

Partner places the API key in the Authorization header of the request.
API server verifies the API key authenticity.

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 code	Description
401	Unauthorized

{
    "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

URLs

Estonia:

Environment	API	Partner Portal
Test	https://demo-api.inbank.ee/partner/v2/ https://demo-api.inbank.ee/partner/v3/	https://demo-partner.inbank.ee/
Production	https://api.inbank.ee/partner/v2/ https://api.inbank.ee/partner/v3/	https://partner.inbank.ee/

Latvia:

Environment	API	Partner Portal
Test	https://demo-api.inbank.lv/partner/v2/ https://demo-api.inbank.lv/partner/v3/	https://demo-partner.inbank.lv/
Production	https://api.inbank.lv/partner/v2/ https://api.inbank.lv/partner/v3/	https://partner.inbank.lv/

Lithuania:

Environment	API	Partner Portal
Test	Please contact us at integration@inbank.lt for test data	https://demo-partner.inbank.lt/
Production	https://api.inbank.lt/partner/v2/ https://api.inbank.lt/partner/v3/	https://partner.inbank.lt/

Czechia:

Environment	API	Partner Portal
Test	https://demo-api.inbank.cz/partner/v2/ https://demo-api.inbank.cz/partner/v3/	https://demo-partner.inbank.cz/
Production	https://api.inbank.cz/partner/v2/ https://api.inbank.cz/partner/v3/	https://partner.inbank.cz/

Poland:

Environment	API	Partner Portal
Test	https://demo-api.inbank.pl/partner/v2/ https://demo-api.inbank.pl/partner/v3/	https://demo-partner.inbank.pl/
Production	https://api.inbank.pl/partner/v2/ https://api.inbank.pl/partner/v3/	https://partner.inbank.pl/

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.

Status	Description
pending	A session is created; The application may be or not be in progress; Positive decisions remain in this status until the contract is concluded or until they expire.
cancelled	The customer has cancelled the process.
granted	Rental has been granted to the customer, there are no obstacles from the Inbank side for sales completion. The process is now waiting for the partner's approval.
completed	This is the target state: the contract between customer and Inbank has been activated, partner is liable for the delivery of goods/services.
declined	Rental was declined by Inbank.
expired	The session was not completed during the defined time period.

The integration flow requires a final partner-side confirmation step in Partner Portal or over API, before the 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 partner has completed the transaction.

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

Contract State Model

Inbank will send callbacks about changes to the 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 partner approval, this state indicates that the rental 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: the contract between customer and Inbank has been activated, partner is liable for the delivery of goods/services.
cancelled	The contract has been cancelled. This state applies only to contracts which previously were `unsigned` or `signed`. For the flow which includes partner approval, `signed` contracts get the status `cancelled` when the partner 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`.

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 application dialog. Regardless of the outcome of the application process, the customer is redirected here, even if rent is not granted.
cancel URL - the URL to which the customer's browser is redirected if the customer deliberately chooses to cancel the application dialog.
callback URL - the URL to which Inbank will send server-to-server callback notifications on session status change events.

Inbank sends callbacks about the following state transition events:

Application is cancelled
Application is denied
Contract is cancelled
Contract is granted (the flow now requires partner approval of the agreement)
Contract is activated (state indicating that the rental agreement is now active)

Once the process is finalised, 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 partner 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 partner 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.

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:

Parameter	Example value	Description
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.
hmac	c196e985640a6291723dc2717d264f82e70126c 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.

Parameter

Example value

Description

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.

hmac

c196e985640a6291723dc2717d264f82e70126c
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. The message body contains:

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 following pages contain charts with demonstrations of the request sequence. The enlisted API requests are used in the following way:

Inbank Smart Rent is available only for cart values, product models, etc. that have been configured in agreement with Inbank. This data is retrieved using the GET /detailed-asset-models endpoint.
The shop retrieves a preliminary monthly payment calculation using the POST /rental/calculations request.
The e-shop initiates a payment session using the POST /pos_sessions endpoint. The redirect_url from the response indicates the link to which the customer is redirected to complete the rental process.
The e-shop redirects the customer to the e-POS environment. In e-POS customers are guided through a number of dialogs to complete the rental process. After the e-POS dialogs, customers are redirected back to the e-shop. The return_url is the one the e-shop included in the POST /pos_sessions request.
As the flow is configured to request partner approval before contract activation, the e-shop waits for the callback indicating that the payment session received the status granted. At this point, the partner needs to approve the rental agreement. This can be done either via the Inbank Partner Portal or via API. The following step is necessary only if the contract was approved.

A. Activate via API

a. The e-shop retrieves the identifier of the contract (contractUuid) using the GET /pos_sessions request.
a. To approve the contract via API, the partner system needs to retrieve the required identifier types for the hero device using the GET /detailed-asset-models endpoint or use previously stored value from step 1.
a. Then, the hero device identifier information needs to be sent to Inbank using the PATCH /contracts/{contractUuid}/asset-identifiers endpoint.
a. Finally, the rental agreement needs to be activated by the partner using the POST /activation endpoint.
a. Contract activation can be verified by calling GET /contracts request If the contract received status activated, the rental agreement has been successful.

B. Activate via Inbank Partner Portal

b. Once the e-shop receives the callback indicating that the payment session received the status completed, the e-shop needs to check the contract status.
b. The e-shop retrieves the identifier of the contract using the GET /pos_sessions request.
b. the e-shop checks the status of the contract using the GET /contracts request. If the contract received status activated, the rental agreement has been successful.

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 contract status to confirm that the rental contract has been successfully concluded.

*Note that step 6a. can also be skipped if identifierTypes were stored from the step 1.

Servers

Demo environment

https://demo-api.inbank.ee/

Live environment

https://api.inbank.ee/

Rental Conditions

Request

The e-shop can retrieve the rental product conditions for each product model via the GET /partner/v3/shops/:shopUuid/rental/products/:productCode/detailed-asset-model?identifierType=:identifierType&identifier=:identifier request. The response includes the minimum and maximum product price values and the rental periods, add-on price range etc These values can then be used to initiate a session with Inbank. The response also includes assetIdentifierTypes which define the required identifier types for assigning asset identifiers.

The request URL includes the product codes provided by Inbank, while the query includes the type of the model identifier that has been agreed with Inbank and the model identifier, from the list of model identifiers provided to Inbank.

Possible identifier type options are:

EAN
MANUFACTURER_PRODUCT_CODE

Security

bearerAuth

Path

shopUuidstringrequired

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

productCodestringrequired

Example: example_code

Query

identifierTypestringrequired

Example: identifierType=EAN

identifierstringrequired

Example: identifier=88845632734657

curl -i -X GET \
  'https://demo-api.inbank.ee/partner/v3/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/rental/products/example_code/detailed-asset-model?identifierType=EAN&identifier=88845632734657' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Returns rental conditions

Bodyapplication/json

idstring

Rental product code.

namestring

Rental product name.

periodsArray of arrays

Rental periods.

assetIdentifierTypesArray of arrays

Asset identifier types. Possible values are IMEI and SERIAL_NUMBER.

identifiersany

The identifier type.

Enum"EAN""MANUFACTURER_PRODUCT_CODE"

subscriptionTotalLimitsobject

insuranceRequirementstring

Information on whether insurance is required.

Enum"INSURANCE_NEVER_APPLIED""INSURANCE_OPTIONAL""INSURANCE_ALWAYS_APPLIED"

tradeInAvailableboolean

Whether trade in is available.

campaignDiscountAvailableboolean

Whether the campaign discount is available.

addOnCategoriesArray of items

Response

application/json

{
  "id": "b748b6b0-58d0-421d-9d52-c7edd22511f1",
  "name": "F731B Galaxy Flip5 5G 512GB Green",
  "periods": [
    12,
    24,
    36
  ],
  "identifiers": [
    { … },
    { … }
  ],
  "assetIdentifierTypes": [
    "IMEI",
    "SERIAL_NUMBER"
  ],
  "subscriptionTotalLimits": {
    "minNetPrice": 5,
    "maxNetPrice": 5000,
    "minGrossPrice": 6,
    "maxGrossPrice": 6000
  },
  "insuranceRequirement": "INSURANCE_OPTIONAL",
  "tradeInAvailable": true,
  "campaignDiscountAvailable": false,
  "addOnCategories": [
    { … },
    { … }
  ]
}

Calculator

Request

To get a monthly payment calculation from Inbank for provided assets, use the POST /partner/v3/shops/:shopUuid/rental/products/:productCode/calculations request. Please note that only one hero device can be sent in calculation request.

Security

bearerAuth

Path

shopUuidstringrequired

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

productCodestringrequired

Example: example_code

Bodyapplication/jsonrequired

periodnumberrequired

Number of months for repayments. Available options are 12, 24 and 36.

insuranceUsedbooleanrequired

Whether insurance is added to the assets. If no value is passed in the request, default value true is used.

assetsArray of itemsrequired

Information on the items that are to be the objects of Smart Rent.

assets[].[0]object(assetsDetails)

grossTradeInAmountnumber

Gross amount for traded-in asset. Can be used only when trade-in is available.

grossCampaignDiscountnumber

Gross amount for campaign discount. Can be used only when campaign discount is available.

curl -i -X POST \
  https://demo-api.inbank.ee/partner/v3/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/rental/products/example_code/calculations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "period": 24,
    "insuranceUsed": true,
    "grossTradeInAmount": 50,
    "grossCampaignDiscount": 40,
    "assets": [
      {
        "netPrice": 1000,
        "type": "MODEL_BASED",
        "modelId": "2797a67c-b0e0-4b64-be81-7c136e16741a",
        "grossPrice": null
      },
      {
        "netPrice": 80,
        "type": "CATEGORY_BASED",
        "modelName": "USB-C Charging cable",
        "grossPrice": null,
        "categoryCode": "add_on"
      }
    ]
  }'

Responses

Creates a new calculation

Bodyapplication/json

grossMonthlyPaymentnumber

The gross monthly payment.

vatnumber

The vat.

netMonthlyPaymentnumber

The monthly net payment.

grossTradeInAmountnumber

The gross trade in amount.

grossCampaignDiscountnumber

The gross campaign discount.

netMonthlyPaymentDiscountnumber

The monthly net payment deduction (due to both campaign discount and trade-in).

totalNetPriceWithDiscountnumber

The total net price including all deductions (both campaign discount and trade-in).

totalGrossPriceWithDiscountnumber

The total gross price including all deductions (both campaign discount and trade-in).

periodnumber

The period.

totalNetPricenumber

The total net price.

totalGrossPricenumber

The total gross price.

assetsArray of items

Information on the items that are to be the objects of Smart Rent.

insuranceRequirementstring

Information on whether insurance is required.

Enum"INSURANCE_NEVER_APPLIED""INSURANCE_OPTIONAL""INSURANCE_ALWAYS_APPLIED"

insuranceUsedboolean

Whether insurance is used.

Response

application/json

{
  "grossMonthlyPayment": 48.01,
  "vat": 8.66,
  "netMonthlyPayment": 39.35,
  "grossTradeInAmount": 50,
  "grossCampaignDiscount": 40,
  "netMonthlyPaymentDiscount": "3.45,",
  "totalNetPriceWithDiscount": "997.21,",
  "totalGrossPriceWithDiscount": "1227.60,",
  "period": 24,
  "totalNetPrice": "1080.00,",
  "totalGrossPrice": "1317.60,",
  "assets": [
    { … },
    { … }
  ],
  "insuranceRequirement": "INSURANCE_OPTIONAL",
  "insuranceUsed": true
}

Session Initiation

Request

POST /partner/v2/shops/:uuid/pos_sessions

To start a payment session in Inbank e-POS, use the POST /shops/:uuid/pos_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.

The customer_data, customer_contact_data and merchant objects and parameters included in them are optional. A request that does not contain these objects will be processed correctly. However, if the body does contain these objects, Inbank will validate the parameters passed inside them. Therefore, if the request contains customer_data/customer_contact_data/merchant objects, their parameters become required.

Security

bearerAuth

Path

shop_uuidstringrequired

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

Bodyapplication/jsonrequired

product_codestringrequired

Reference to product code.

currencystringrequired

Currency code in uppercase. Available option is EUR.

localestringrequired

Language - country codes, for example et-ET.

valid_untilstring(date-time)

The point in time when the payment session is to expire. E.g. 2021-02-17T11:10:00+02:00. After this time, the customer will not be able to complete the financing procedure.

user_ipstring

Customer browser IP address as seen by e-shop.

customer_datastringrequired

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

identity_code*
first_name*
last_name*
gender - options: m (male), f (female).

customer_contact_datastringrequired

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

email*
mobile*

purchaseobjectrequired

purchase.purchase_referencestring

Unique identifier of the shopping cart or order in the e-shop (i.e. order ID).

purchase.descriptionstringrequired

Textual description of the order or shopping cart, meaningful for the customer.

purchase.additional_detailsobject

Any additional details about the order that are not covered with predefined parameters.

purchase.merchantArray of items

Array of items containing information about the merchant supplying the purchase.

rental_application_dataobjectrequired

Information on the items that is to be the object of Smart Rent.

rental_application_data.insurance_usedboolean

Whether insurance is added to the assets. If no value is passed in the request, default value true is used.

rental_application_data.gross_campaign_discountnumber

The gross amount of the campaign discount.

rental_application_data.gross_trade_in_amountnumber

The gross amount of the traded in asset.

rental_application_data.assetsArray of itemsrequired

Information on the items that are to be the objects of Smart Rent.
Please note, that the hero device (this is the main device that is rented) needs to be first in the list of assets.

rental_application_data.assets[].[0]object(postPostSessionDetails)

rental_application_data.periodnumberrequired

Smart Rent duration in month.

partner_urlsobject

integration_infostring

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

additional_datastring

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

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": "smart_rent_product_code",
    "currency": "EUR",
    "locale": "et-ET",
    "valid_until": "2025-02-17T11:10:00+02:00",
    "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"
    },
    "purchase": {
      "purchase_reference": "ORDER_000001",
      "description": "Description of ORDER_000001 order",
      "merchant": {
        "merchant_order_reference": "T21093289",
        "merchant_domain_name": "wwww.example.com"
      },
      "additional_details": {
        "description": "Purchase additional details"
      }
    },
    "user_ip": "192.128.00.01",
    "customer_data": {
      "first_name": "John",
      "last_name": "Smith"
    },
    "customer_contact_data": {
      "email": "john.smith@session.pos",
      "mobile": "51231412"
    },
    "rental_application_data": {
      "period": 12,
      "insurance_used": false,
      "grossTradeInAmount": 80,
      "grossCampaignDiscount": 10,
      "assets": [
        {
          "net_price": 332.5,
          "category_code": "computer",
          "model_name": "iPad 10.2\" 2021 WiFi 64GB - Space Grey",
          "model_id": "c1234c56-0000-1111-2222-f1bc23456e7a",
          "type": "MODEL_BASED"
        },
        {
          "net_price": 31.3167,
          "category_code": "add_on",
          "model_name": "COMMA Magnet Leather Folio for iPad PRO 11'\'''\'' Black*",
          "type": "CATEGORY_BASED"
        }
      ]
    },
    "integration_info": {
      "ecom_platform": "magento",
      "module": "inbank-2.1.0",
      "extra_key_3": "#3"
    },
    "additional_data": {
      "key_1": "key1",
      "key_2": "key2",
      "key_3": "key3"
    }
  }'

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 customer is to be redirected to complete the rental 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"
}

Session Details

Request

When a user is redirected back to e-shop, or when a callback notification is received, the e-shop should make a GET /shops/:shop_uuid/pos_sessions/:pos_session_uuid request to inspect session details. The response contains the credit_contract_uuid value which is used in the GET /contracts request to check the status of the contract.

The response partly reflects the data that was submitted on session initiation, but also includes some important attributes to be used. It is important to inspect the value of the status. If the status is completed, then from the e-shop order perspective it has been paid, and the goods can be shipped.

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

statusstring

Session status.
Payment for the e-shop order can be considered successfully completed when the status = completed.
For more details, see the State model chapter.

credit_application_uuidstring

Identifier of the application in Inbank systems.
This parameter appears in the response once the customer has submitted the application during dialogs.
Example: b1904cd8-f5b0-4610-b87c-97a512d6125f

credit_contract_uuidstring

The unique identifier of the contract associated with the session. This identifier is used in the GET /:contract_uuid/contracts request to check the status of the rental agreement.

Response

application/json

{
  "uuid": "be8ba2de-6100-4903-98d5-000000000000",
  "product_code": "smart_rent_product_code",
  "total_amount": "1640.0",
  "currency": "EUR",
  "status": "pending",
  "locale": "et-ET",
  "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"
  },
  "rental_application_data": {
    "period": 12,
    "insurance_used": true,
    "grossTradeInAmount": 80,
    "grossCampaignDiscount": 10,
    "assets": [ … ]
  },
  "purchase": {
    "description": "example text",
    "uuid": "b499968a-e95e-4bb5-8beb-0354f3ff4191",
    "items": [],
    "created_at": "2024-04-11T14:46:37+02:00"
  },
  "created_at": "2024-04-11T14:46:37+02:00",
  "valid_until": "2024-04-18T14:46:37+02:00",
  "show_expiration_counter": false,
  "credit_application_uuid": "f2f281f8-79fe-4ed2-9b40-000000000000",
  "credit_contract_uuid": "c315e587-9c2e-4928-8f34-000000000000",
  "customer_uuid": "7d225626-ed39-400e-80e5-000000000000",
  "shop_public_name": "Shop"
}

Asset Identifier assigment

Request

Once the device is to be provided to the customer, the identifiers of the device, its IMEI and/or serial number, need to be provided to Inbank The list of required identifiers is included in the response of the Rental Conditions endpoint.

Please note that the identifier is needed only for the hero device under the Smart Rent contract. There is no need to add identifiers for the add-ons.

Security

bearerAuth

Path

shopUuidstringrequired

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

productCodestringrequired

Example: example_code

contractUuidstringrequired

UUID of the contract where asset identifier needs to be added. This UUID is part of the response to the Session Details request.

Example: d315a2c6-7a01--0000-1111

Bodyapplication/jsonrequired

assetIdentifiersArray of itemsrequired

The asset identifiers.

assetIdentifiers[].[0]object(assetIdentifiers)

curl -i -X PATCH \
  https://demo-api.inbank.ee/partner/v3/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/rental/products/example_code/contracts/d315a2c6-7a01--0000-1111/asset-identifiers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "identifierType": "IMEI",
      "identifier": "355889000000007"
    },
    {
      "identifierType": "SERIAL_NUMBER",
      "identifier": "J7P3D7000000"
    }
  ]'

Responses

Submit asset identifiers

Response

No content

Contract Activation

Request

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

Once the identifiers of the hero device are sent to Inbank, the contract should be approved. This will trigger the contract activation process on the Inbank side and you should receive a callback with the status completed once the contract is activated.

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

Security

bearerAuth

Path

shop_uuidstringrequired

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

contract_uuidstringrequired

UUID of the Smart Rent contract. The contract UUID is part of the response to the Session Details request.

Example: 788ec8c4-c497-470b-8505-2303f151d427

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

Responses

Contract approval

Response

No content

Contract Details

Request

Once the contract UUID has been retrieved via the GET /pos_sessions request, the e-shop can check the status of the 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 rental agreement is active 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.

uuidstring

Contract UUID.

numberstring

Contract number.

payout_account_numberstring

Payout bank account number.

activated_atstring

Contract activated at.

activator_namestring

Contract activator name.

terminated_atstring

Contract terminated at.

product_codestring

Product code.

customer_signedstring(date-time)

Customer signed at.

rep_signedstring(date-time)

Rep signed at.

signed_atstring(date-time)

Signed at.

partner_approval_atstring(date-time)

Partner approval at.

customer_uuidstring

Contract customer UUID.

identification_satisfiedboolean

Customer identification acceptance status for contract.

Response

application/json

{
  "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": "smart_rent_product_code",
  "customer_signed": null,
  "rep_signed": null,
  "signed_at": null,
  "partner_approval_at": null,
  "customer_uuid": "40837f6d-0000-0000-0000-59a5b1efedd8",
  "identification_satisfied": true
}

Integration Guide for Inbank Smart RentCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Introduction

Flow Overview

Demo Environment

Guidelines for Integration Implementation

API Connectivity

Authentication

Authorization Header

Content-Type

URLs

Payment Session State Model

Contract State Model

Callbacks

Request Structure

Callback Request Example

Callback Message Content

Callback Authenticity Validation

API Requests

API Request Flow

Rental Conditions

Request

Responses

Was this helpful?

Calculator

RequestExpand all

Responses

Was this helpful?

Session Initiation

RequestExpand all

Responses

Was this helpful?

Session Details

Request

Responses

Was this helpful?

Asset Identifier assigment

RequestExpand all

Responses

Was this helpful?

Contract Activation

Request

Responses

Was this helpful?

Contract Details

Request

Responses

Was this helpful?

Request

Request

Request