Contents:

1. General information

   1. Bank Products

   2. Integration Process

2. Methods

   1. Get Calculations

      1. Examples

   2. Register Applications

      1. Examples

   3. Get Application Status

   4. Get Application Data

3. Ready embedded calculator

4. Express buy button in product page

5. Add to cart functionality

6. Example files

Open

This document serves as a guide for merchants to integrate with the TBI Bank loan application platform using the provided API. The platform can be accessed through the following URLs:

• Test Environment: https://banklyuat.tbibank.bg/#/login

• Production Environment: https://bnkl.tbibank.bg/#/login

Upon registering for a partnership with TBI Bank, merchants will receive access to these platforms to track all incoming loan applications. This guide refers to the platform as the "Merchant Portal." Merchants will also be provided with a 'reseller code' (a four-character code) and a 'reseller key' to identify the store or object when using the API methods.

Bank Products

TBI Bank offers various repayment schemes:

• Loan terms range from 3 to 60 months.

• Loan amounts range from 100 to 30,000 BGN.

• Options include standard loans and "Buy Now, Pay Later" schemes.

• Terms and interest rates are agreed upon with the Merchant Enabler (a TBI Bank employee responsible for the merchant).

• Interest rates can vary based on the loan amount, with options for 0% rates and promotional schemes for specific periods. These terms are also arranged with the Merchant Enabler.

Integration Process

The integration process for sending loan applications is divided into two main parts:

Part 1: Display Financing Options

1. Display Financing Button:

   • Show a button on the product page saying "Buy in installments starting from XX.XX per month" or "Buy in X installments for XX.XX / monthly."

   • Use the GetCalculations API method to calculate the installment amount (XX.XX).

2. Show All Pay Schemes:

   • Allow the customer to view all available pay schemes with different periods.

   • Display this information on both the product and checkout pages.

   • Ensure that the following EU-compliant parameters are displayed: APR, NIR, Total Due Amount, Installment, and Period. These details are provided by the GetCalculations method.

Part 2: Submit Loan Application

1. Send Loan Application:

   • Use the RegisterApplication API method to send client data (e.g., Full Name, Phone Number, Address) and shopping cart items to the bank.

   • The only mandatory fields are the items list and the order ID from the merchant's website.

   • The RegisterApplication method returns a URL where the customer completes the application. This URL can be used to redirect the customer or display a pop-up on the website.

   • Preferably, send customer data in the API call to prefill the application form, enhancing customer satisfaction.

Extra: Update Application Status

• Check Application Status:

  • Use the GetApplicationStatus endpoint to retrieve the current status of an application and track its status changes throughout the processing.

By following these steps, merchants can seamlessly integrate with the TBI Bank loan application platform, offering flexible financing options to their customers and ensuring a smooth application process.

The GetCalculations API call provides a RESTful response with available repayment schemes for a specific merchant or store. It supports both GET and POST requests. The response includes all necessary parameters to display repayment schemes in compliance with EU requirements and to facilitate sending applications to the bank processing platform.

To optimize performance, it's recommended to update the parameters once per day, preferably after the first scheme request of the new day or after 00:01 daily. A manual pull update API call from the merchant backend is also advisable if different interest rate conditions are set up.

However, if the API is called for each calculation, the response remains efficient and easy to handle.

Endpoint

<https://beta.tbibank.support/api/GetCalculations>

Request Parameters

Response Parameters

1. Basic Request

   Request:

   <https://beta.tbibank.support/api/GetCalculations?reseller_code=TBI1&reseller_key=EX1>

   Response:

   [ { "id": 755, "name": "3 месеца ПРОМО 0%", "bank_product": "Promo 0%", "period": 3, "installment_factor": 0.3333333, "total_due_factor": 1, "nir": 0, "apr": 0, "amount_min": 100, "amount_max": 1200, "category_id": 255 }, { "id": 1, "name": "3 месеца", "bank_product": "Standard 0.61%", "period": 3, "installment_factor": 0.33940643333333, "total_due_factor": 1.0182193, "nir": 10.9, "apr": 10.09, "amount_min": 10000, "amount_max": 30000, "category_id": 0 }, { "id": 474, "name": "12 месеца", "bank_product": "Standard 1.50%", "period": 12, "installment_factor": 0.098333333333333, "total_due_factor": 1.18, "nir": 31.72, "apr": 34.91, "amount_min": 100, "amount_max": 5000, "category_id": 0 } ]

2. Filtered by Amount

   Request:

   <https://beta.tbibank.support/api/GetCalculations?reseller_code=TBI1&reseller_key=EX1&amount=1500>

   Response:

   [ { "id": 474, "name": "12 месеца", "bank_product": "Standard 1.50%", "period": 12, "installment_factor": 0.098333333333333, "total_due_factor": 1.18, "nir": 31.72, "apr": 34.91, "amount_min": 100, "amount_max": 5000, "category_id": 0 } ]

3. Empty Request

   Request:

   <https://beta.tbibank.support/api/GetCalculations>

   Response:

   { "error": 203, "message": "Empty request /api/info203" }

4. Invalid Request

   Request:

   <https://beta.tbibank.support/api/GetCalculations?test=test>

   Response:

   { "error": 204, "message": "Invalid request /api/info204" }

5. Unauthorized Access

   Request:

   <https://beta.tbibank.support/api/GetCalculations?reseller_code=TBI1&reseller_key=UNAUTH>

   Response:

   { "error": 205, "message": "Access denied /api/info205" }

6. Valid Authorization with No Schemes

   Request:

   <https://beta.tbibank.support/api/GetCalculations?reseller_code=TBI1&reseller_key=EMPTY>

   Response:

   []

Example cURL Commands

1. Form Data POST Request

   curl --location '<https://beta.tbibank.support/api/GetCalculations>' \\ --form 'reseller_code="TBI1"' \\ --form 'reseller_key="EMPTY"'

2. JSON POST Request

   curl --location '<https://beta.tbibank.support/api/GetCalculations>' \\ --header 'Content-Type: application/json' \\ --data '{"reseller_code":"TBI1","reseller_key":"EX1","category_id":"255","amount":"1000"}'

3. Text/Plain POST Request

   curl --location '<https://beta.tbibank.support/api/GetCalculations>' \\ --header 'Content-Type: text/plain' \\ --data '{"reseller_code":"TBI1","reseller_key":"EX1","category_id":"255","amount":"1000"}'

The RegisterApplication method sends customer and order data to TBI Bank. If the data is valid, the response includes a URL to which the customer should be redirected to complete the application. This endpoint supports only the POST method.

For testing, use the following credentials:

Endpoint

<https://beta.tbibank.support/api/RegisterApplication>

Request Parameters

Encrypted JSON Parameters

The encrypted JSON containing application information includes the following parameters:

Items List Parameters

Input:

and contains the following JSON:

Examples with optional fields:

The body of the application from the above example will have Promo scheme preselected and the application will have both successRedirectURL and failRedirectURL defined.

The body of the application from the above example will have a period of 34 months preselected and the application will receive status updates at https://tbi-uat.online/endpoint/status-update awaiting post update with body for Standard repayment plans from 3 to 60 months:

And body for BNPL:

Standard application status variations:

1. Missing Parameters:

Indicates that the request is missing required parameters.

2. Total Basket Amount Outside Financing Ranges:

Indicates that the total basket amount exceeds the allowable financing limits.

3. Incorrect Reseller Code or Key Matching, or Incorrect Encryption:

Indicates that there is an issue with the reseller code, key matching, or encryption used.

4. Incorrect Parameters:

Indicates that there are incorrect parameters provided in the request's items list.

After successfully sending an application, the response will include an order_id and token. You can use these, along with the reseller_code and reseller_key, to request and track the application's status and its movement through the assessment process. This API endpoint exclusively supports the POST method.

• Interface: https://beta.tbibank.support/api/GetApplicationStatus

Parameters

Examples

Input:

Output:

Here, store_order_id refers to the order ID on the merchant's side, which is sent in the Register Application method.

After successfully sending an application, the response will include an order_id and token. You can use these, along with the reseller_code and reseller_key, to request and track the application's data and some of its details like store_order_id (the id in the merchants store), latest status, downpayment, installment and period of the loan application. This API endpoint exclusively supports the POST method.

• Interface: https://beta.tbibank.support/api/GetApplicationData

Parameters

Examples

Input:

Output:

Here, store_order_id refers to the order ID on the merchant's side, which is sent in the Register Application method. status is the latest status of the application. downpayment is either NULL (if not downpayment is used or not eligible for the merchant) or a double value - the amount of downpayment selected by the customer. installment is the amount of the monthly installment of the remaining amount. period is an integer and show the selected period of the application.

Using the reseller_code, reseller_key, and the total basket amount, you can call a dynamic URL to present available repayment schemes:

• Calculator with Total Amount → code=TBI1&key=EX1&amount=1000

• Calculator with Total Amount and Category → code=TBI1&key=EX1&amount=1000&category=255

In the tbi system, additional schemes can be added depending on the category ID. For example, the second link above triggers two more schemes, which are only available for category ID 255. This category ID should also be sent in the item list category field.

An express buy with tbi button can be implemented in product page using a callback if customer finishes the application in tbi redirected URL. To use this option the merchant need an endpoint which will receive a POST message with a body similar to tbi RegisterApplication with encrypted data. This endpoint needs to return 'order_id' that is created in the merchant website.

If the order_id has value 0 when registering the initial application tbi will send back the information with customer details back to the mechant and will use the returned order_id to be visible in Merchant Portal.

Integration Process Overview:

1. Merchant Initialization: Send the application with missing data and "orderid": "0" as follows:

2. TBI Response: TBI will respond with:

3. Decryption: Decrypt the data field to obtain the following JSON format. Note that the period can represent either a period in months or 'BNPL'. Also, the sku field is replaced with code in the items list:

On choosing a scheme and/or downpayment, our calculator’s JS will return a message via

The content of the message will be a JSON in the following format as example

The Merchants website must catch this message and read it

Example code to include:

We need the scheme_id and/or downpayment to be accessible in checkout. If they are - then include them in the RegisterApplication request, just like that:

– can be used as a reference to get repayments schemes. registerApplication.php – an example application encryption and cURL request getStatusUpdate.php – an example cURL for status update

– an encryption model file for encrypting sensitive data in the Register Application method.

For different programming languages additional model files can be provided