0% found this document useful (0 votes)
65 views8 pages

ECommerce - API Documentation

Uploaded by

jc42b6hv7m
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOC, PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
65 views8 pages

ECommerce - API Documentation

Uploaded by

jc42b6hv7m
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOC, PDF, TXT or read online on Scribd
You are on page 1/ 8

Introduction

This document contains technical information on how to integrate with the eCommerce platform.

API URLs

We have different endpoints for UAT and Live environment

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

The credentials should be sent as a part of the encrypted request.

You receive the credentials from TBI integration team.

If the credentials are missing or wrong eCommerce will respond with 401 Unauthorized.
! Credentials are case sensitive!

API - Finalize method

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.

This value must be an unencrypted text, for exemple merchant_ro.

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

✓ Convert the json object to json string


✓ Encrypt the json string using the rsa asymmetric algorithm
Two pairs of encryption keys are provided but TBI integration team. One used for sending
applications to TBI and has SFTL_ in the name and one that is used for decrypting the status updated
received from TBI.

An exemple of calling the post method in PHP:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->paymentUrl);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");

curl_setopt($ch, CURLOPT_POSTFIELDS, ['order_data' => $output,


'providerCode ' => 'tbitestapi_ro']);

curl_setopt($ch, CURLOPT_RETURNTRANSFER,
1); curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);


curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);

$response = curl_exec($ch);
$header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size); $body =
substr($response, $header_size);

print_r('Curl error: ' . curl_error($ch)."\n\r");


var_dump($response); exit;

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 .

The application statuses are :

✓ Approved (status_id = 1 and motiv = „”)


✓ Cancel (status_id = 0 and motiv = „”)
✓ In pending (status_id = 2 and motiv = „”)
✓ Rejected (status_id = 0 and motiv „Respins Biroul de Credit” sau motiv = „Criterii eligibilitate”)

The encryption algorithm

The steps of the encryption algorithm are :

✓ 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);

//Encrypted data file_put_contents('keys/encrypted',


base64_encode($output));
C# Example
public string Encrypt(string decryptedString)
{
var path = System.IO.Directory.GetCurrentDirectory();
X509Certificate2 key = new X509Certificate2(path + "\\keys\\pub.pfx", "password");
RSA csp = (RSA)key.PublicKey.Key;
byte[] plainTextBytes = Encoding.UTF8.GetBytes(decryptedString);
int blockSize = (int)Math.Ceiling(key.PublicKey.Key.KeySize / 8m) - 11;
List<byte> cipherTextBytes = new List<byte>();
for (int chunkPosition = 0; chunkPosition < plainTextBytes.Length; chunkPosition +=
blockSize)
{
int chunkSize = Math.Min(blockSize, plainTextBytes.Length - chunkPosition);
cipherTextBytes.AddRange(csp.Encrypt(
plainTextBytes.Skip(chunkPosition).Take(chunkSize).ToArray(),RSAEncryptionPadding.Pkcs1));
}
return Convert.ToBase64String(cipherTextBytes.ToArray());

The decryption algorithm

The steps of the decryption algorithm are :


✓ Decode from base64 the request
✓ Calculate the block size. The formula for calculating the block size is (s / 8) , where s is the
private key size.
✓ Divide the request in pieces having the length of the block size. Decrypt every piece and
concatenate every result of the decryption to the one before

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);

// Get the private Key


if (!$privateKey =
openssl_pkey_get_private(file_get_contents('keys/pkey'), 'password')) {
die('Private Key failed');
}
$a_key = openssl_pkey_get_details($privateKey);
var_dump($a_key);

/ Decrypt the data in the small chunks


$chunkSize = ceil($a_key['bits'] / 8);
$output = '';
$encrypted = base64_decode(file_get_contents('keys/encrypted'));
while ($encrypted) {
$chunk = substr($encrypted, 0, $chunkSize);
$encrypted = substr($encrypted,
$chunkSize); $decrypted = '';
if (!openssl_private_decrypt($chunk, $decrypted, $privateKey))
{ die('Failed to decrypt data');
$output .= $decrypted;
}
openssl_free_key($privateKey);

echo ($output);
An C# exemple :

public string Decrypt(string cipherText)


{
var path = System.IO.Directory.GetCurrentDirectory();
byte[] cipherTextBytes = Convert.FromBase64String(cipherText);

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());
}

Steps that must be covered by TBI integration team

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

OPTIONAL – Cancel by customer.

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:

Send Cancel requests PROD https://ecommerce.tbibank.ro/Api/LoanApplication/CanceledByCustomer


https://vmrouatftos01.westeurope.cloudapp.azure.com/LoanApplication/
Send Cancel requests UAT CanceledByCustomer

 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”
}

order_data – Result after the encryption process of the Object


providerCode - Will be the one provided in the credential mail, same as in the /Finalize request.

 Response
If the request is done correct you will receive this response:
{
"isSuccess": true,
"error": null
}

You might also like