Callback Message Content

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

Documentation version 4.01, 16.04.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 and Integration Testing Requirements

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.

To ensure that the integration works correctly, we kindly ask you to share a link to the test environment of your e-commerce site with us so we can verify the integration before starting Live sales.

In order to verify that the full integration is working correctly, at a minimum, the following test should be executed with at least 2 different asset models using demo environment:

Create and activate a rental contract with all possible/configured add-on codes, following the steps in API request flow
Verify that the asset model name, identifiers and price, as well as add-on prices match with values in your e-shop. Asset and add-on information can be reviewed in the Partner Portal. If the Partner Portal is not used, our Partner Onboarding team will assist in verifying that the data is correct.

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/yourShopUuid/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/v3/	https://demo-partner.inbank.ee/
Production	https://api.inbank.ee/partner/v3/	https://partner.inbank.ee/

Latvia:

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

Lithuania:

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

Czechia:

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

Poland:

Environment	API	Partner Portal
Test	https://demo-api.inbank.pl/partner/v3/	https://demo-partner.inbank.pl/
Production	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, customer has made the first payment, there are no obstacles from the Inbank side for sales completion. The process is awaiting device identifiers after rental package is issued for customer and contract activation.
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 about device handover to the customer in Partner Portal or over API, before the application process is completed.

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	Customer has made the first payment upon session state `granted`. 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`. `Signed` contracts get the status `cancelled` when the partner has not approved the contract.
terminated	An existing 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 redirectUrl, via the customer's browser.
Second one is server-to-server callback which ensures that the partner receives the callback. It is done on callbackUrl.

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

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 /asset-identifiers endpoint.
a. Finally, the rental agreement needs to be activated by the partner using the POST /activation endpoint. Ideally, activation should be done only after the customer has received the shipped device (picked it up from the parcel machine or received it by any other means). Alternatively, activation can be done when the device is shipped.
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. The partner representative needs go to Inbank Partner Portal to assign required asset identifiers to hero device of rental contract and approve the rental.
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

GET /partner/v3/shops/:shopUuid/rental/products/:productCode/detailed-asset-model?
identifierType=:identifierType&identifier=:identifier

The e-shop can retrieve the rental product conditions for each product model using this API request. The response includes the minimum and maximum product price values, available rental periods, add-on price range, etc. These values can then be used to initiate a session with Inbank. Additionally, the response contains assetIdentifierTypes, which define the required identifiers needed to activate the contract after the rental product is issued.

The request URL includes the product codes provided by Inbank. NB! The product code for the Demo and Live environments may differ! The query includes the type of model identifier and the identifier value ("EAN" or "MANUFACTURER_PRODUCT_CODE"). Only models that have been pre-approved and priced by Inbank will get a response. NB! In Demo environment only limited list of models are available. Applicable models are agreed prior to launch and shared with Inbank via a MS Excel file, for which we will provide the template and assist if needed. Only hero device are required, add-ons you will be able to post depending on customer selection (within agreed categories and min/max agreed for each category prior to launch).

There are two options for hero device pricing setup:

Preferred option: We agree on a fixed price for Inbank Rent for the month (or longer) for the selected hero device. In this case, there is no need to send us the existing retail price over API, but we will provide you a monthly rental payment based on the agreed fixed price for the period.
Alternative option: Not fixing the prices for Inbank Rent. In this case, you will send us a valid retail net price during contract creation and, based on it, get back a monthly rental payment.

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

POST /partner/v3/shops/:shopUuid/rental/products/:productCode/calculations

The e-shop can use this request to get a monthly payment calculation from Inbank for provided devices. 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 for model are provided in Rental Conditions API response e.g. 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/v3/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 - posSessionUuid and the URL to which the customer is to be redirected - redirectUrl.

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

The customerData, customerContactData 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 customerData/customerContactData/merchant objects, their parameters become required.

Security

bearerAuth

Path

shopUuidstringrequired

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

Bodyapplication/jsonrequired

productCodestringrequired

Reference to product code.

currencystringrequired

Currency code in uppercase. Available option is EUR.

localestringrequired

Language - country codes, for example et-ET.

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

userIpstring

Customer browser IP address as seen by e-shop.

customerDatastringrequired

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

identityCode*
firstName*
lastName*
gender - options: m (male), f (female).

customerContactDatastringrequired

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

email*
mobile*

purchaseobjectrequired

purchase.purchaseReferencestring

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

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.

rentalApplicationDataobjectrequired

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

rentalApplicationData.insuranceUsedboolean

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

rentalApplicationData.grossCampaignDiscountnumber

The gross amount of the campaign discount.

rentalApplicationData.grossTradeInAmountnumber

The gross amount of the traded in asset.

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

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

rentalApplicationData.periodnumberrequired

Smart Rent duration in month.

partnerUrlsobject

integrationInfostring

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

additionalDatastring

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/v3/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/pos-sessions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "productCode": "smart_rent_product_code",
    "currency": "EUR",
    "locale": "et-ET",
    "validUntil": "2025-02-17T11:10:00+02:00",
    "partnerUrls": {
      "returnUrl": "https://campaign.inbank.ee/tmp/post.php?type=return",
      "cancelUrl": "https://campaign.inbank.ee/tmp/post.php?type=cancel",
      "callbackUrl": "https://campaign.inbank.ee/tmp/post.php?type=callback"
    },
    "purchase": {
      "purchaseReference": "ORDER_000001",
      "description": "Description of ORDER_000001 order",
      "merchant": {
        "merchantOrderReference": "T21093289",
        "merchantDomainName": "wwww.example.com"
      },
      "additionalDetails": {
        "description": "Purchase additional details"
      }
    },
    "userIp": "192.128.00.01",
    "customerData": {
      "firstName": "John",
      "lastName": "Smith"
    },
    "customerContactData": {
      "email": "john.smith@session.pos",
      "mobile": "51231412"
    },
    "rentalApplicationData": {
      "period": 12,
      "insuranceUsed": false,
      "grossTradeInAmount": 80,
      "grossCampaignDiscount": 10,
      "assets": [
        {
          "netPrice": 332.5,
          "modelName": "iPad 10.2\" 2021 WiFi 64GB - Space Grey",
          "modelId": "c1234c56-0000-1111-2222-f1bc23456e7a",
          "type": "MODEL_BASED"
        },
        {
          "netPrice": 31.3167,
          "categoryCode": "add_on",
          "modelName": "COMMA Magnet Leather Folio for iPad PRO 11'\'''\'' Black*",
          "type": "CATEGORY_BASED"
        }
      ]
    },
    "integrationInfo": {
      "ecomPlatform": "magento",
      "module": "inbank-2.1.0",
      "extraKey3": "#3"
    },
    "additionalData": {
      "key1": "key1",
      "key2": "key2",
      "key3": "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"

redirectUrlstring

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",
  "redirectUrl": "https://demo-epos.inbank.ee/session/5e3a459a-aada-4d81-b6ad-09cb9483c8bf"
}

Session Details

Request

GET /partner/v3/shops/:shopUuid/pos-sessions/:posSessionUuid

When a user is redirected back to e-shop, or when a callback notification is received, the e-shop should make a GET /shops/:shopUuid/pos-sessions/:posSessionUuid request to inspect session details. The response contains the creditContractUuid 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

shopUuidstringrequired

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

posSessionUuidstringrequired

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

curl -i -X GET \
  https://demo-api.inbank.ee/partner/v3/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.

creditApplicationUuidstring

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

creditContractUuidstring

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

Response

application/json

{
  "uuid": "be8ba2de-6100-4903-98d5-000000000000",
  "productCode": "smart_rent_product_code",
  "totalAmount": "1640.0",
  "currency": "EUR",
  "status": "pending",
  "locale": "et-ET",
  "partnerUrls": {
    "returnUrl": "https://campaign.inbank.ee/tmp/post.php?type=return",
    "cancelUrl": "https://campaign.inbank.ee/tmp/post.php?type=cancel",
    "callbackUrl": "https://campaign.inbank.ee/tmp/post.php?type=callback"
  },
  "rentalApplicationData": {
    "period": 12,
    "insuranceUsed": true,
    "grossTradeInAmount": 80,
    "grossCampaignDiscount": 10,
    "assets": [ … ]
  },
  "purchase": {
    "description": "example text",
    "uuid": "b499968a-e95e-4bb5-8beb-0354f3ff4191",
    "items": [],
    "createdAt": "2024-04-11T14:46:37+02:00"
  },
  "createdAt": "2024-04-11T14:46:37+02:00",
  "validUntil": "2024-04-18T14:46:37+02:00",
  "showExpirationCounter": false,
  "creditApplicationUuid": "f2f281f8-79fe-4ed2-9b40-000000000000",
  "creditContractUuid": "c315e587-9c2e-4928-8f34-000000000000",
  "customerUuid": "7d225626-ed39-400e-80e5-000000000000",
  "shopPublicName": "Shop"
}

Device Identifier Assigment

Request

PATCH /partner/v3/shops/{shopUuid}/rental/products/{productCode}/contracts/{contractUuid}/asset-identifiers

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 device 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 device identifiers

Response

No content

Contract Activation

Request

POST /partner/v3/shops/:shopUuid/rental/products/:productCode/contracts/:contractUuid/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. Ideally, activation should be done right after the customer has received the shipped device (picked it up from the parcel machine or received it by any other means). Alternatively, when agreed with Inbank, activation can be done when the device is shipped.

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

Security

bearerAuth

Path

shopUuidstringrequired

The unique identifier of the shop.

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

productCodestringrequired

Example: example_code

contractUuidstringrequired

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/v3/shops/a93f1f44-d5dd-4469-bfcc-c1de9e969213/rental/products/example_code/contracts/788ec8c4-c497-470b-8505-2303f151d427/activation \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Contract approval

Response

No content

Contract Details

Request

GET /partner/v3/shops/:shopUuid/rental/products/:productCode/contracts/:contractUuid

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/v3/shops/:shopUuid/contracts/:contractUuid request. The response will include the status parameter. If the status is activated, the rental agreement is active, then all required steps are completed.

Security

bearerAuth

Path

shopUuidstringrequired

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

productCodestringrequired

Example: example_code

contractUuidstringrequired

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

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

Responses

Returns contract details

Bodyapplication/json

statusstring

Contract status.

uuidstring

Contract UUID.

referenceNumberstring

Contract reference number.

activatedAtstring(date-time)

Contract activated at.

activatorNamestring

Contract activator name.

productCodestring

Product code.

partnerApprovalAtstring(date-time)

Partner approval at.

customerUuidstring

Contract customer UUID.

detailsobject

Response

application/json

{
  "status": "signed",
  "uuid": "11d1baeb-1da1-1c01-b111-12111211c1a1",
  "referenceNumber": "89001350000",
  "activatedAt": null,
  "activatorName": null,
  "productCode": "smart_rent_product_code",
  "partnerApprovalAt": null,
  "customerUuid": "40837f6d-0000-0000-0000-59a5b1efedd8",
  "details": {
    "grossTradeInAmount": 100,
    "grossCampaignDiscount": null,
    "totalNetPriceWithDiscount": 360,
    "totalGrossPriceWithDiscount": 470.4,
    "totalNetPrice": 460,
    "totalGrossPrice": 570.4,
    "insuranceUsed": true,
    "rentalSchedule": { … },
    "assets": [ … ]
  }
}

Contract Cancellation

Request

POST /partner/v3/shops/:shopUuid/contracts/:contractUuid/cancel

To cancel the contract, the e-shop first needs to perform the GET /pos-sessions request, which, among other parameters, returns the creditContractUuid. This identifier can then be used to cancel the credit contract.

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

Security

bearerAuth

Path

shopUuidstringrequired

Example: a93f1f44-d5dd-4469-bfcc-c1de9e969213

contractUuidstringrequired

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

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

Responses

Cancel contract

Response

No content

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 and Integration Testing Requirements

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?

Device Identifier Assigment

RequestExpand all

Responses

Was this helpful?

Contract Activation

Request

Responses

Was this helpful?

Contract Details

Request

Responses

Was this helpful?

Contract Cancellation

Request

Responses

Was this helpful?

Request

Request

Request