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:
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:
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:
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.
The authentication process consists of the following two steps:
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"
]
}
The HTTP header Content-Type application/json is expected in all requests, unless otherwise specified in the endpoint description. Example:
Content-Type: application/json
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 | https://demo-api.inbank.lt/partner/v2/ https://demo-api.inbank.lt/partner/v3/ |
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/ |
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.
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 For the flow which includes partner approval, |
terminated | An existing credit contract has been terminated. This state can only be applied to contracts which previously were activated . |
When initiating the payment session in Inbank Partner API the e-shop should provide 3 URLs:
Inbank sends callbacks about the following state transition events:
Once the process is finalised, Inbank will send two callbacks, both with the same structure and content:
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:
pos_session
identifier either from the incoming message, or from the internal database as it was persisted when the session was initiated.pos_session
status and process the order payment status based on the pos_session
state. If needed, you can also check the purchase reference.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. |
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×tamp=1553072069
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.
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);
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 representative needs to approve the rental via the Inbank Partner Portal. The following step is necessary only if the contract was approved.
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. First, the e-shop retrieves the identifier of the contract using the GET /pos_sessions request. Then 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.
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.
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 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:
Returns rental conditions
Unauthorized
Forbidden
Not Found
Internal Server Error
{- "id": "b748b6b0-58d0-421d-9d52-c7edd22511f1",
- "name": "F731B Galaxy Flip5 5G 512GB Green",
- "periods": [
- 12,
- 24,
- 36
], - "identifiers": [
- {
- "type": "EAN",
- "value": "8806095012803"
}, - {
- "type": "MANUFACTURER_PRODUCT_CODE",
- "value": "SM-F731BLGHEUE"
}
], - "subscriptionTotalLimits": {
- "minNetPrice": 5,
- "maxNetPrice": 5000,
- "minGrossPrice": 6,
- "maxGrossPrice": 6000
}, - "withoutInsuranceAvailable": true,
- "tradeInAvailable": true,
- "addOnCategories": [
- {
- "assetType": "CATEGORY_BASED",
- "code": "add_on",
- "name": "Add-on",
- "type": "ADD_ON",
- "minPrice": 1.17,
- "maxPrice": 583.33,
- "minNetPrice": 1.17,
- "maxNetPrice": 583.33,
- "minGrossPrice": 1,
- "maxGrossPrice": 700,
- "assetIdentifierRequired": false
}, - {
- "assetType": "CATEGORY_BASED",
- "code": "copying_fee",
- "name": "Copying fee",
- "type": "ADD_ON",
- "minPrice": 1.17,
- "maxPrice": 3.33,
- "minNetPrice": 1.17,
- "maxNetPrice": 3.33,
- "minGrossPrice": 1.5,
- "maxGrossPrice": 7,
- "assetIdentifierRequired": false
}
]
}
To get a monthly payment calculation from Inbank for the amount in general and also per asset, if applicable, use the POST /partner/v3/shops/:shopUuid/rental/products/:productCode/calculations
request.
Creates a new calculation
Unauthorized
Forbidden
Not Found
Internal Server Error
{- "period": 24,
- "insuranceUsed": true,
- "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"
}
]
}
{- "grossMonthlyPayment": 51.22,
- "vat": 8.89,
- "netMonthlyPayment": 42.33,
- "netTradeInAmount": null,
- "netMonthlyPaymentTradeInDeduction": null,
- "totalNetPriceWithTradeInDeduction": null,
- "period": 24,
- "totalNetPrice": 1080,
- "totalGrossPrice": 1306.8,
- "assets": [
- {
- "modelName": "F731B Galaxy Flip5 5G 256GB Green",
- "name": "F731B Galaxy Flip5 5G 256GB Green",
- "status": "DRAFT",
- "categoryType": "ASSET",
- "categoryCode": "phone",
- "categoryName": "Phone",
- "netPrice": 1000,
- "grossPrice": 1210,
- "vat": 210,
- "identifier": null,
- "identifierType": "IMEI",
- "residualValue": 450,
- "netMonthlyPayment": 37.5,
- "grossMonthlyPayment": 45.38,
- "modelId": "2797a67c-b0e0-4b64-be81-7c136e16741a",
- "type": "MODEL_BASED"
}, - {
- "modelName": null,
- "name": null,
- "status": "DRAFT",
- "categoryType": "ADD_ON",
- "categoryCode": "add_on",
- "categoryName": "Add-on",
- "netPrice": 80,
- "grossPrice": 96.8,
- "vat": 16.8,
- "identifier": null,
- "identifierType": "SERIAL_NUMBER",
- "residualValue": 0,
- "netMonthlyPayment": 4.83,
- "grossMonthlyPayment": 5.84,
- "type": "CATEGORY_BASED"
}
], - "insuranceUsed": true
}
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.
Creates a new POS session
Unauthorized
Forbidden
Not Found
Internal Server Error
{- "product_code": "smart_rent_product_code",
- "currency": "EUR",
- "locale": "et-ET",
- "valid_until": "2025-02-17T11:10:00+02:00",
- "partner_urls": {
}, - "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,
- "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"
}
}
{- "uuid": "5e3a459a-aada-4d81-b6ad-09cb9483c8bf",
- "status": "pending",
}
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.
Return POS session details
Unauthorized
Forbidden
Not Found
Internal Server Error
{- "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": {
}, - "rental_application_data": {
- "period": 12,
- "insurance_used": true,
- "assets": [
- {
- "category_code": "apple_iphone",
- "net_price": "820.0",
- "type": "CATEGORY_BASED",
- "model_name": "iPhone 11 Pink"
}, - {
- "net_price": "820.0",
- "type": "MODEL_BASED",
- "model_id": "8806095012803",
- "model_name": "Samsung Galaxy"
}
]
}, - "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"
}
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.
Returns contract details
Unauthorized
Forbidden
Not Found
Internal Server Error
{- "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
}