ECommerce - API Documentation
ECommerce - API Documentation
This document contains technical information on how to integrate with the eCommerce platform.
API URLs
Live environment
The API for the Romanian production environment can be found at
https://ecommerce.tbibank.ro/Api/LoanApplication/Finalize
Testing environment
The API for the Romanian testing environment can be found at
https://vmrouatftos01.westeurope.cloudapp.azure.com/LoanApplication/Finalize
Authentication
To be able to send applications to TBI platform you need to use API Credentials. The credentials
consist of three elements:
• Store_id – This is your Merchant identification code – used to identify order origin
• Username - used to authorize use of ecommerce’s APIs
• Password - used to authorize use of ecommerce’s APIs
If the credentials are missing or wrong eCommerce will respond with 401 Unauthorized.
! Credentials are case sensitive!
The Finalize method is used to create (register) a credit application for the customer requesting it.
It is a http: POST method. This method accepts two parameters: order_data and providerCode.
The type of this parameters is string.
The value of the parameter providerCode is used to identify the merchant that make the request and
use the correct decrypting key.
For creating the value for order_data the following steps must be covered:
Create a json object with customer and shopping cart information’s like is the next example:
{
"store_id":"tbitestapi_ro",
"order_id":"cata1234",
"back_ref":"https://retoolapi.dev/el8C9J/tbiapi",
"order_total":"1600",
"username":"test",
"password":"MZWlyiuAIbnyT0UO",
"customer":{
"fname":"Catalin",
"lname":"Test",
"cnp":"",
"email":"[email protected]",
"phone":"0752000000",
"billing_address":"",
"billing_city":"",
"billing_county":"",
"shipping_address":"",
"shipping_city":"",
"shipping_county":"",
"instalments": "24",
"promo":0
},
"items":[
{
"name":"Ceas smartwatch , GPS, Senzor H10 HR, Black",
"qty":"1.0000",
"price":1600,
"category":"2",
"sku":"DTZ1MCBBM",
"ImageLink":""
}
]
}
The properties that are with red font mandatory. The description of every property of the json object
from above is written in the next lines:
- store_id (string) : the merchant code, this value must be the same as providerCode
- order_id (whole number) : the unique order id
- back_ref (string) : the url that is called every time that the status of the application changes
- order_total (numeric) : the value of the shopping cart
- fname (string) : the firstname of the customer
- lname (string) : the lastname of the customer
- cnp (string) : the pin of the customer
- email (string) : the email of the customer
- phone (
- shipping_city (string) : the shipping city for the order
- shipping_county (string) : the shipping county for the order
- promo : 1/ 0 represents that the banking product that the customer is applying for has/hasn’t
interest
- instalments (string) : the number of the instalments
- name (string) : the name of the object that the customer want to buy
- imagelink (string) : the link of the product image (visible on internet)
- qty (numeric) : the quantity of the object selected
- price (numeric) : the price of the object that the customer want to buy
- category (whole number) : the category of the object that the customer want to buy
- sku (string) : the sku of the object that the customer want to buy
- username (string) : the merchant identifier that is used for authorization purpose
- password (string) : the password for the merchant that is used for authorization purpose
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->paymentUrl);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
1); curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
$response = curl_exec($ch);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size); $body =
substr($response, $header_size);
The response to this call contains on the location header field an URL that the client must be
redirected to.
"HTTP/2 301
location:
https://vmrouatftos01.westeurope.cloudapp.azure.com/TBILandingPage/Home/Index/?
url=aHR0cHM6Ly92bXJvdWF0ZnRvczAxLndlc3RldXJvcGUuY2xvdWRhcHAuYXp1cmUuY29tL0IyQ1By
b3h5L2VjP3Nlc3Npb25JZD03M2Y4MThlMi1hYmIwLTQ3NTQtYjk4ZC03MDA1MjY1NDhmNDcmY3VsdHVy
ZT1yby1STw==&link2payid=b79a0fe9-43ce-4982-9f20-345b22b5646b
API – ReturnToProvider method
The ReturnToProvider method is used to send the status of the application back to merchant. A json
object is created using the application information like is the next example :
var order_data =
{
"order_id": "145003523",
"status_id": "0",
"motiv": " Criterii eligibilitate",
};
The description of every property of the json object from above is written in the next lines:
- order_id : the unique order id received from the merchant
- status_id : 0/1/ 2 ( 0 – rejected/canceled, 1 – approved, 2 – pending)
- motiv : rejection reason (if the application is rejected) / intermediate status (if the application
is in pending)
The json object from above is encrypted using the merchant public key. The result of the
encryption is put in a parameter with the name order_data and then with this information is made a post
call to the link that was received on the initial request .
✓ Calculate the block size. The formula for calculating the block size is (s / 8) – 11, where s is the
public key size.
✓ Divide the json string in pieces having the length of the block size and encrypt every piece separately
✓ Create a result variable and concatenate the value resulted after every encryption to the one before
✓ Convert the result to base64
In the next lines are written two examples of encryption algorithm, one for php and C#
<?php
ini_set('display_errors', 1);
error_reporting(E_ALL);
$post = [
'store_id' => 'tbitestapi_ro',
'order_id' => '423423423',
'back_ref' => 'https://retoolapi.dev/el8C9J/tbiapi,
'order_total' => '1234.00',
'username' => 'tbitestapi',
'password' => 'MZWlyiuAIbnyT0UO',
'customer' => [
'fname' => 'popescu',
'lname' => 'maria',
'cnp' => '100000000000',
'email' => '[email protected]',
'billing_county' => 'Bucuresti',
'shipping_address' => 'bldv. unirii nr 1',
'shipping_city' => 'Bucuresti',
'shipping_county' => 'Bucuresti',
'promo' => 0
],
'items' => [[
'name' => 'Smartphone SAMSUNG Galaxy S8 Plus 64GB Blue',
'imagelink' => 'https://merchant.ro/img/samsunggalaxys8.jpg',
'qty' => 1,
'price' => '800',
'category' => '2',
'sku' => 'TABT285NZAB'
],[
'name' => 'Smartphone SAMSUNG Galaxy S1',
'imagelink' => 'https://merchant.ro/img/samsunggalaxys1.jpg',
'qty' => 1,
'price' => '200',
'category' => '2',
'sku' => 'TABT285NZAB'
]]
];
var_dump($post);
echo $plaintext = json_encode($post);
$publicKey = openssl_pkey_get_public(file_get_contents('keys/public.key'));
$a_key = openssl_pkey_get_details($publicKey);
// Encrypt the data in small chunks.
$chunkSize = ceil($a_key['bits'] / 8) - 11;
$output = '';
while ($plaintext)
{ $chunk = substr($plaintext, 0,
$chunkSize); $plaintext = substr($plaintext,
$chunkSize); $encrypted = '';
if (!openssl_public_encrypt($chunk, $encrypted, $publicKey)) { die('Failed
to encrypt data'); }
$output .= $encrypted; }
openssl_free_key($publicKey);
In the next lines are written two examples of decryption algorithm , one for php and the other for C#.
An Php exemple :
<?php
ini_set('display_errors', 1);
error_reporting(E_ALL);
echo ($output);
An C# exemple :
X509Certificate2 key;
key = new X509Certificate2(path + "\\keys\\priv.pfx", "password"); RSA csp =
(RSA)key.PrivateKey;
int blockSize = (int)Math.Ceiling(key.PrivateKey.KeySize / 8m); List<byte>
plainTextBytes = new List<byte>();
for (int chunkPosition = 0; chunkPosition < cipherTextBytes.Length;
chunkPosition += blockSize)
{
int chunkSize = Math.Min(blockSize, cipherTextBytes.Length -
chunkPosition); plainTextBytes.AddRange(csp.Decrypt(
cipherTextBytes.Skip(chunkPosition).Take(chunkSize).ToArray(),
RSAEncryptionPadding.Pkcs1));
}
return Encoding.UTF8.GetString(plainTextBytes.ToArray());
}
✓ Provide credentials
✓ Set up merchant in UAT and LIVE environment
✓ Upload encryption keys on TBI server
✓ Allocate financial products for integrated merchant
✓ Test connections before sending integration package to merchant
Testing
For testing, please contact TBI integration team to help you in testing applications in UAT environment.
We offer the option for merchants to send cancel request for individual requests. This method can be used before
Approval.
Call method: POST
End-points:
Object structure:
{
"orderId" : "250752148",
"statusId" : "1",
"username" : "tbitestapi",
"password" : "MZWlyiuAIbnyT0UO"
}
orderId – Order number sent in the initial request;
statusId – Always 1;
Request
The request sent to the Refund end-point must be encrypted using the same method as the /Finalize using the same
public.key.
Content-Type: "application/x-www-form-urlencoded"
{
"orderData" : “YZ19ztb4knPshzQn+i2MOxzuhn7ed3z55g/m+AeuDg7y0HZBHcHVPnx1AywKkkAuu”
"encryptCode" : “tbitestapi_ro”
}
Response
If the request is done correct you will receive this response:
{
"isSuccess": true,
"error": null
}