Estonia Checkout

How to get started

On this page you will find information about how to authenticate with the Checkout Estonia Backend API, construct the authentication header and how to Initialize payment.

Required steps

Obtain “Partner access token”
Intialize payment
Redirect to TB Bank Estonia checkout
Query for payment status

API Authentication

Base URLs

Avarda base URLs for Checkout Estonia Backend API:

Staging environment:

Backend API: https://avdonl-s-checkout-estonia.westeurope.cloudapp.azure.com

Frontend Application: https://avdonl-s-checkout-est.azurewebsites.net/

Production environment:

Backend API : https://avdonl-p-checkout-estonia.westeurope.cloudapp.azure.com

Frontend Application: https://jarelmaks.tfban k .ee

1. Obtain “Partner access token”

“Partner access token” is used as authentication for all further communication with the Checkout Estonia Backend API. This token should never be displayed to the user or sent to the frontend of the application. Access token is valid for one hour (3600s).

ClientId and ClientSecret that is required for access is generated by TFBank Partner support: tonis.mand@tfbank.ee

To obtain the token send POST request with clientId and clientSecret as a JSON to /api/Partner/token.

# Obtain "Partner access token"
POST {api_url}/api/Partner/token
Content-type: application/json

{
  "clientId": "659e57c9-d970-4db8-b003-8ba04cc157f9",
  "clientSecret": "4~{x*6%gvBt(:aD"
}

Request Payload:

Property	Data type
`clientId`	string
`clientSecret`	string

Example

<?php
$api_url = "https://avdonl-s-checkout-estonia.westeurope.cloudapp.azure.com";
// Use your CLIENT_ID and CLIENT_SECRET
$client_id = "659e57c9-d970-4db8-b003-8ba04cc157f9";
$client_secret = "4~{x*6%gvBt(:aD";

// Send POST request and save "Partner access token"
$access_token_url = "$api_url/api/Partner/token";
$data = array('clientId' => $client_id, 'clientSecret' => $client_secret);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($access_token_url, false, $context);
if ($result === false) { /* Handle error */ };

$json_data = json_decode($result);
$partner_access_token = $json_data->token;
?>

Return value:

# Partner access token response
Content-type: application/json

{
"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImFQY3R3X29kdlJPb0VOZzNWb09sSWgydGlFcyIsImtpZCI6ImFQY3R3X29kdlJPb0VOZzNWb09sSWgydGlFcyJ9..."
}

Property	Data type
`token`	string

2. Initialize payment

Initialize payment and set up initial parameters such as: language; items list; etc. Please check the full list of options below.

Send a POST request with “Partner access token” as authorization obtained from api/Partner/token with JSON data. Successful initialization returns a purchase ID. Purchase ID is used in other Checkout Estonia Backend API calls.

# Initialize payment
POST {api_url}/api/Partner/payment
Content-type: application/json
Authorization: Bearer {partner_access_token} 

{
  "items": [
    {
      "description": "string",
      "amount": 50,
      "notes": "string"
    }
  ],
  "orderReference": "string",
  "merchantReturnUrl": "string",
  "campaignCode": "string",
  "useCustomStyles": false,
  "language": "English",
  "customerDetails": {
    "email": "string",
    "phone": "string",
    "zip": "string",
    "street": "string",
    "city": "string"
  }
}

Payload

Property	Data type	Description
`language`	enum	Language which application should be displayed in. Supported values: English/Estonian/ Default value: Estonian
`items`	[]	List of items
`orderReference`	string	Partner custom ID reference.
`merchantReturnUrl`	string	Return url to partner when payment is completed.
`campaignCode`	string	If campaign for loan should be used
`useCustomStyles`	boolean	Use partner custom style to style the payment views.
`customerDetails`	customerDetails	contact and address details for prefilling of input fields

Items

Property	Data type	Description
`description`	string	Item description
`amount`	decimal	Item amount
`notes`	string	Additional item notes
`taxAmount`	decimal	Optional – can be omitted – VAT amount
`taxCode`	string	Optional – can be omitted – VAT code in string format e.g. “20%”

CustomerDetails

Property	Data type	Description
`email`	string	Customer email
`phone`	string	Customer phone
`zip`	string	Customer zipcode
`street`	string	Customer street address
`city`	string	Customer city

Example

<?php
$api_url = "https://avdonl-s-checkout-estonia.westeurope.cloudapp.azure.com";
// "Partner access token" generated by calling `$api_url/api/Partner/token`: 
$partner_access_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

// Send POST request, save session access token and purchase ID
$init_payment_url = "$api_url/api/Partner/payment";
$payment_data = array(
    "language" => "English",
    "orderReference" => "950d48a0-9f82-443a-8bac-5a28b78b30eb",
    "merchantReturnUrl" => "https://myeshop.test.com/checkoutReturn",
    "useCustomStyles" => false,
    "campaignCode" => "",
    "items" => array(array(
        "description" => "Some item description",
        "notes" => "",
        "amount" => 50
    )),
);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\nAuthorization: Bearer $partner_access_token\r\n",
        'method'  => 'POST',
        'content' => json_encode($payment_data)
    )
);
$context  = stream_context_create($options);
$init_result = file_get_contents($init_payment_url, false, $context);
if ($init_result === false) { /* Handle error */ };

$init_data = json_decode($init_result);
$purchase_id = $init_data->purchaseId;
?>

Return Value

# Partner initialize payment response
Content-type: application/json

{
    "purchaseId": "4ulSln"
}

3. Redirect

When purchaseId has been obtained user has to be redirected to Estonia Checkout

Redirect url stage env: https://avdonl-s-checkout-est.azurewebsites.net/?purchaseId=4ulSln

Redirect url production env: https://jarelmaks.tfbank.ee/?purchaseId=4ulSln

When the checkout proces is completed the user is redirected to merchantReturnUrl specified in initialize payment request. Purchase id parameter is added to this url on redirect.

Example redirect url: https://myeshop.test.com/checkoutReturn?purchaseId=4ulSln

4. Query Payment status

After payment has been completed Partner and user is redirected back to Partners website it is important that Partner query TFBank Estoina Checkout for status. Main reason for query TFBank Estonia for status is to get accurate information about the purchase status prevent some fake values created in client browser.

Send a GET request with “Partner access token” as authorization obtained from api/Partner/token to api/Partner/Payment/{purchaseID} and Estonia checkout will respond with JSON data containing all information we gathered during the payment.

Payment/{purchaseId} query can be called at any application state and time after first initialize payment has been called and TFBank unique purchaseId reference has been received.

# Get payment status
GET {api_url}/api/Partner/payment/{purchaseId}
Content-type: application/json
Authorization: Bearer {partner_access_token}

Return value

# Partner payment response
Content-type: application/json

{
  "esigningApplicantUrl": "string",
  "purchaseId": "string",
  "state": "string",
  "documentId": "string",
  "orderNumber": "string",
  "totalPrice": 0,
  "creditLimit": 0,
  "signed": true,
  "customer": {
    "customerId": "string",
    "ssn": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phone": "string",
    "street": "string",
    "city": "string",
    "zip": "string",
    "country": "string"
  },
  "items": [
    {
      "description": "string",
      "amount": 0,
      "taxAmount": 0,
      "taxCode": "string",
      "notes": "string"
    }
  ]
}

Payload

Property	Data type	Description
`items`	[{}]	List of Item objects
`purchaseId`	string	Purchase ID for current session. TFBank unique reference.
`state`	string	Current application state description
`documentId`	string	Application contract document Id
`orderNumber`	decimal	Partner order reference
`creditLimit`	string	Approved credit limit
`signed`	boolean	Loan contract electronically signed or not
totalPrice	decimal	approved loan amount incl vat
customer	{}	Customer details

Items

Property	Data type	Description
`items`	[{}]	List of Item objects
`description`	string	Item description
`amount`	decimal	Item amount
`taxAmount`	decimal	VAT amount
`taxCode`	string	VAT code (%)
`notes`	string	Item notes

Customer

Property	Data type	Description
`customer`	{}	object
`customerId`	string	TFBank customer id
`ssn`	string	Customer ssn
`firstName`	string	Customer first name
`lastName`	string	Customer last name
`email`	string	Customer email
`phone`	string	Customer phone
`street`	string	Customer street address
`zip`	string	Customer zipcode
`city`	string	Customer city

Application State(s)

Application has different states – each state represent were in the application process the purchase session exists.

LoginStep – Application waiting for completion of login step

ConsentStep – Application is waiting for concent to be completed.

ApplicationApprovedStep – Application pre approved – waiting for customer payment terms confirmation.

ApplicationPartlyApprovedStep – Application was partly pre approved with lower amount than requested – waiting for customer payment terms confirmation.

ApplicationRejectedStep – Application rejected. Customer can restart process or return to merchant.

ClientDetailsStep – Application fully or partly approved – waiting for client details and final customer confirmation

SignContractStep – Digital contract signing – waiting for customer digital signature.

SignAsGuestStep – Customer applied manually, without digital contract signing. Waiting for customer confirmation.

CompletedRequiresManualSigningStep – Application is completed manually without digital contract signing. Customer will sign contract via courier or sign physically when receiving the goods.

CompletedStep – Application is completed with contract digitally signed, goods are ok to deliver.

SignFailedStep – Contract signing failed.