Created with Sketch.
Created with Sketch.
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

  1. Obtain “Partner access token”
  2. Intialize payment
  3. Redirect to TB Bank Estonia checkout
  4. 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.tfbank.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:

PropertyData type
clientIdstring
clientSecretstring

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..."
}
PropertyData type
tokenstring

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": 0,
      "taxAmount": 0,
      "taxCode": "string",
      "notes": "string"
    }
  ],
  "orderReference": "string",
  "merchantReturnUrl": "string",
  "campaignCode": "string",
  "useCustomStyles": true,
  "language": "English",
  "customerDetails": {
    "email": "string",
    "phone": "string",
    "zip": "string",
    "street": "string",
    "city": "string"
  }
}

Payload

PropertyData typeDescription
languageenumLanguage which application should be displayed in.
Supported values: English/Estonian/
Default value: Estonian
items[]List of items
orderReferencestringPartner custom ID reference.
merchantReturnUrlstringReturn url to partner when payment is completed.
campaignCodestringIf campaign for loan should be used
useCustomStylesbooleanUse partner custom style to style the payment views.
customerDetailscustomerdetailscontact and address details for prefilling of input fields

Items

CustomerDetails

PropertyData typeDescription
CustomerDetails{}Object
descriptionstringitem description
amountdecimalamount of the item
taxamountdecimalvat amount for the item
taxcodestringvat code % for item
notesstringItem notes

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,
        "taxCode" => "20",
        "taxAmount" => 42
    )),
);

$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

PropertyData typeDescription
items[{}]List of Item objects
purchaseIdstringPurchase ID for current session. TFBank unique reference.
statestringCurrent application state description
documentIdstringApplication contract document Id
orderNumberdecimalPartner order reference
creditLimitstringApproved credit limit
signedbooleanLoan contract electronically signed or not
totalPricedecimalapproved loan amount incl vat
customer{}Customer details

Items

PropertyData typeDescription
items[{}]List of Item objects
descrptionstringItem description
amountdecimalItem amount
taxAmountdecimalVAT amount
taxCodestringVAT code (%)
notesstringItem notes

Customer

PropertyData typeDescription
customer{}object
customerIdstringTFBank customer id
ssnstringCustomer ssn
firstNamestringCustomer first name
lastNamestringCustomer last name
emailstringCustomer email
phonestringCustomer phone
streetstringCustomer street address
zipstringCustomer zipcode
citystringCustomer 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.