NAV
cURL java-OkHttp python-Request C#-RestSharp

Introduction

Welcome to Tarabut Gateway (TG) API platform documentation. Here you will find everything you need to build features, apps, and experiences using TG API services.

All our endpoints follow standard RESTful principles. You will find all the example request and response payload snippets along with detailed parameters and field descriptions to get you up and running quickly.

For you to start interacting with our APIs, please sign up for access to the right developer portal based on your country of operation.

Country Developer Portal URL
Bahrain https://portal.tarabutgateway.io/sign-up
Saudi Arabia https://portal.sau.tarabutgateway.io/sign-up

You will be provided with access to Developer Portal where you can create and manage the API keys and App settings required for the service.

If you have any questions, please navigate to our Enquiry page.

Environment URLs

TG has two environments -

  1. Sandbox environment where you try and test your integration without requiring live bank accounts.
  2. Production environment where you will take the integration live for real users. This environment is fully scalable and designed to work with live banks.
Country Domain Url
Bahrain Sandbox : https://api.sandbox.tarabutgateway.io
Production : https://api.tarabutgateway.io
Saudi Arabia Sandbox : https://api.sau.sandbox.tarabutgateway.io
Production : https://api.sau.tarabutgateway.io

A few points to know:

Once you are ready to go to Production, you can request the production keys by emailing us at sales@tarabutgateway.com.

Getting Started Guide

This overview of how to incorporate Tarabut Gateway products/services into your product (known as an integration) outlines the broad requirements for using the Tarabut Gateway platform and connects you to resources for choosing and implementing the best Open Banking solutions for your platform.

1. Create a free developer account

A TG developer account enables you to develop and test your app in an environment that’s isolated from production. API calls sent from this environment are not actual transactions and are simulated to closely match the production API calls and user journeys.

Developer Portal Urls by country :-

Country Developer Portal URL
Bahrain https://portal.tarabutgateway.io/sign-up
Saudi Arabia https://portal.sau.tarabutgateway.io/sign-up

Depending on the TG APIs you plan to work with, you may need to take additional steps to gain access to your desired functionality.

To start testing our APIs in sandbox and to gain access to abundant bank dummy data, create your developer account today!

2. Generate Sandbox Credentials

Next, you generate your sandbox credentials in your developer account. On the TG platform, sandbox credentials are a set of API client_id and client_secret.

You can create an app by following the below steps :-

3. Configure app settings

After you generate your sandbox credentials, you may then proceed further to configure your

Note: If you do not provide a display name, then by default the display name will be taken as the company name.

Note: You can set multiple redirect URIs to your integration on the developer portal.

4. Generate your Access Token

Once you've generated your sandbox credentials and have configured your app settings in your developer portal account, you’re ready to continue developing/integrating.

In order to make a successful sandbox API call, you need to first generate an Access Token.

These sandbox credentials can be used to obtain OAuth2 access token. The access token must be supplied as a Bearer token under headers within every service API call made to TG platform.

Authentication API
Obtain access token which is required for accessing services | Country | Domain Url | | --------------------------------------------------------------------------------------- | ----------------------------------------------------- | | Bahrain | Sandbox : https://api.sandbox.tarabutgateway.io
Production ** : https://api.tarabutgateway.io | |Saudi Arabia*
| **Sandbox* : https://api.sau.sandbox.tarabutgateway.io
*Production * : https://api.sau.tarabutgateway.io |

Endpoint : /auth/v1/token Method : POST

Request Body Parameters Description
clientId Pass the sandbox client_id generated on the developer portal.
clientSecret Pass the sandbox client_secret generated on the developer portal.
grantType Pass a static value client_credentials to this parameter.
redirect_uri Pass the redirect_uri that you configured on the developer portal under the app settings page.

Note: The Access Token expires after 300 sec.

Sample Request

{
"clientId": "4039c150-335b-4b8b-ab66-eca6953xxxxx",
"clientSecret": "rpSFlA6xeuSzI7ZJVIgW3Yyskakxxxxx",
"grantType": "client_credentials",
"redirect_uri": "http://localhost:3000/landingpage"
}

Sample Response

{
    "accessToken": "eyJraWQiOiI5N2UzZTQ0NS0wZWU1LTRiNmItODVmOC1hNmY4YTMzMjYzZTIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0ZW5hbnRfaWQiOiJ0YXJhYnV0X2dhdGV3YXkiLCJhdWQiOiJodHRwczovL2FwaS5zYXUuc2FuZGJveC50YXJhYnV0Z2F0ZXdheS5pbyIsImlzcyI6Imh0dHBzOi8vYXBpLnRhcmFidXRnYXRld2F5LmlvL2F1dGgiLCJjbGllbnRfY291bnRyeSI6IlNBVSIsInRnX2NsYWltcyI6WyJwYXllZTp3cml0ZSIsInBheW1lbnQ6d3JpdGUiLCJwYXllcjp3cml0ZSIsInN0YXR1czpyZWFkIl0sImN1c3RvbWVyX3VzZXJfaWQiOiI2Njc4IiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly93d3cuZ29vZ2xlLmNvbSIsImV4cCI6MTY4NjczOTM3MCwiaWF0IjoxNjg2NzM5MDcwLCJjbGllbnRfbmFtZSI6IlRHICIsImNsaWVudF9pZCI6IjQwMzljMTUwLTMzNWItNGI4Yi1hYjY2LWVjYTY5NTM2ZDBiOSJ9.C7YVROTTVSXFXTSb5fkeEZKiMqJDJehxGmloi4VIiB9TxuIuxfVrlrLzUTDAOjryydBHKJb8AOpLJGBBCFIPBJY7Dw-WMnLn6lSjGMQkBiTKbktDSJ1_QLME7aTK8rvRwgSLXtGVzGDo3i1TK-9nD8EUvV022h8w3mmABIH_KCxFwensLYfDw_-iTCuHqQz1XXQT3Y8ZcHxTmaG8zKW3gs3m11b_b59q4zRBdTWKW60nVbduFfR8unrFy-CPqtVo3S96_DYfTnGeTrcm_XJ4p9guHTOK0RXEl86GiVp4Yc9meMz47uWOHAYoIPBCbJEsMmxxxxxxxxxxxxxxxxxxxx",
    "expiresIn": 300,
    "tokenType": "Bearer"
}

5. Go-Live

After you have completed your integration and are ready to go-live, you need to follow the following steps to request for production access :-

i. Login to DevPortal :-

Login to your dev portal account and navigate to the app settings page.

ii. Click on LIVE mode :-

Once you're on the app settings page you need to click on the *LIVE mode toggle.

iii. Request for production access :-

Once you click the LIVE mode toggle, you have to click on the "Request for production credentials" button.

iv. Complete KYB :-

Once you have requested for production access, we will create a support ticket and you'll receive an email in your registered email address which will ask you to complete the KYB with TG.

v. Make 1st production API call :-

Once the KYB is completed, you'll get a notification regarding KYB completion and you'll be able to see the API production credentials on the developer portal. You can then make your 1st production API call and go-to-market!

API Protocols

The service is made available through Application Programming Interface (API) endpoints, all of which adhere to REST design principles. Standard HTTP verbs and status codes are used for requests and response statuses. Request and response payloads are of JSON format.

To ensure data security and privacy, TG API is served over HTTPS TLS v1.2+ protocol only.

Request Headers

The following header attributes are required to be sent for almost all API calls and the body must have a valid JSON. API specific headers are documented along with respective APIs.

Sample Header Attributes

Content-Type: application/json
Authorization: Bearer <your_access_token>
X-TG-IdempotencyKey: <unique_idempotency_key>
X-TG-UserLoginTime: <your_user_last_loggedin_time>
X-TG-UserIPAddress: <your_user_IP_address)
X-TG-DeviceUserAgent: <your_user_device_UserAgent)
Header Key Value Description
Content-Type application/json Represents the format of the payload being provided in the request. This must be set to application/json, except for the endpoints that support Content-Type other than application/json
Authorization Bearer <your_access_token> Credentials (Generated from /token end point) to be provided to the Authorisation or Resource Server in Bearer Authentication Scheme.
Required except for /token endpoint.
X-TG-IdempotencyKey <Unique_Key> Unique request identifier to support idempotency for POST Methods.
Must be less that 40 chars.
X-TG-UserIPAddress <User_IP_Address> User's/PSU's IP address if they are currently logged in with your application.
X-TG-DeviceUserAgent <User-Agent_from
user's_device>		 Indicates the user-agent from the device or the browser that the Customer/PSU is using.
X-TG-UserLoginTime <Your_User's
login Time		 The time when the user/PSU last logged in with your application in ISO-8601 format (YYYY-MM-DDTHH:mm:ssZ)
ex: 2021-10-13T13:01:15Z

Note: The X-TG-UserIPAddress header identifies whether or not the user is present, which the provider may utilize to authorize data updates/API queries if the user is present.

The passing of the User IP address and Device User-Agent header value to TG may be subject to Data Privacy regulations and concerns.

Success Response

The successful responses will have status codes 200 or 201 and have relevant response content where required. However, 204 No Content and 205 Reset Content status codes won't contain response content.

All our responses will be in JSON format with UTF-8 encoding.

Error Response

We use standard HTTP response codes for success and failure notifications. In general, 40X codes are for developer or user-related failures, and 50X codes are for TG related issues.

You can read about each error codes, description and sample response here.

Sample Error Response

Http Status Code: 400

{
"error": "INVALID_FIELDS",
"errorMessage": "Required fields missing or invalid field or field values sent in the request",
"details":[
{
"fieldName": "paymentAmount.value",
"message": "must not be null"
}
],
"traceId": "233333"
}
Field Type Description
error string Unique short error code, enough to understand the error as well as use it in code. New error codes may be added as we introduce new features and enhance functionalities.
errorMessage string Descriptive error message that helps debugging and understand the cause for failure. This can change over time and is not safe to use in code.
details Object[]
nullable		 An array of error details providing more details around error (like field specific level).
  fieldName string
nullable		 The actual field name which failed validation or for which the error was thrown.
  message string
nullable		 Descriptive error message specifying the reason for failure for the field.
traceId string Unique trace Id that must be shared with TG support team to help debug when you face any issue.

Data Types

Data Type Standard
string encoding UTF-8
dateTime ISO-8601 (YYYY-MM-DDTHH:mm:ssZ)
date ISO-8601 (YYYY-MM-DD)
currency code ISO-4217 (BHD)
country code ISO 3166-1 alpha-3 (BHR)
number (float) Up to 3 decimals

Money Schema

We use a money object for all amounts or balances (both request and response) which includes an amount value along with a currency code

Sample Money Response

{
  "value": 100.123,
  "currency": "BHD"
}
Field Type Description
value number The actual amount value Amounts are always returned up to 3 decimal places depending on the currency.
currency string Currency code associated with amount. Supports all ISO 4217 currency codes.

Sample First Page Pagination Link Object (for Account Transactions)

{
  "rel": "FIRST",
  "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=1"
}

We use a link object to return API references for other related API calls. It could be for pagination or other related entities.

Field Type Description
rel string The relationship of the link.
href string The link to request the resource.

Product Overview

Before we get started, let's look at the products that are supported and will allow you to leverage open banking to its fullest potential.

Payment Initiation Overview

Take away the complexity of bank integrations and deliver a world-class product!

Set-up open banking enabled bank to bank payments for a wide range of use cases, including bill payments, e-commerce checkouts and account funding.

Why TGPay?

Products/Services Endpoints
Authentication APIs
Obtain access token which is required for accessing services		 /auth/v1/token
Provider APIs
Fetch the list of supported banks		 /v1/providers
Payment Initiation
Initiate and manage payments through your App		 /paymentInitiation/v1/payments

Account Information Overview

Easily plug TG Connect to get secure, user consented access to bank account balances and transactions and innovate by building unique solutions!

Orchestrate open banking enabled account data access for a variety of use cases from PFM to Lending.

Account information through TG is simple through our easy to integrate Account Information APIs and TGConnect - our frontend widget!

Why TGConnect?

Products/Services Endpoints
Authentication APIs
Obtain access token which is required for using the services		 /auth/v1/token
Provider APIs
Fetch the list of supported banks		 /v1/providers
Account Information
Initiate bank connection and access account balances and transactions		 /accountInformation/v1/intent
/accountInformation/v1/accounts
/accountInformation/v1/accounts/{accountId}/transactions

Versioning

The API base URL contains a version identifier. Each endpoint will refer to the latest version in the document.

Backward Compatibility

Tarabut Gateway aims to make integration as seamless as possible for its client and takes all possible steps to prevent backward-compatibility breaks. In the scenario where a change is unavoidable, we either create a new endpoint by renaming the url or updating the version.

Tarabut Gateway considers the following changes to be backwards-compatible or non-breaking changes:

Using Postman to access TG's APIs

Being able to try out an API as quickly as possible is instrumental when learning about the API's features. One of the tools to help you get up and running quickly is Postman, which allows you to organize and run groups of REST API calls. We have added a Postman collection for both Bahrain and Saudi Arabia users who will be able to access these APIs and mak

Step 1: Install Postman

Before you can use Postman, you need to install it. Visit https://www.getpostman.com/ and download the preferred version for your system.

Step 2: Get the Postman collection

This step is easy. Just click on the Run in Postman button on this page and you’ll be prompted to import the collection inside of Postman.

Run in Postman

Configure Environment and API Keys

Once you import the collections, navigate to the Collections tab on the left sidebar and you can see a folder named Tarabut Gateway API Endpoints that contains all required APIs. The Collection uses Postman environment variables to simplify each API request.

All what you have to do is:

  1. Select the Tarabut Gateway API Collection

  2. Click the Variables tab

  3. Copy your API keys from Dev Portal. Update the ClientId and ClientSecret.

  4. Save your changes and start making API requests!

Further information on managing Postman environments can be found here.

Step 3: Try out the APIs!

Now it’s time to try out some API calls in Postman!

Our collection has a few folders in it, each with different API calls to fulfill a different task, along with a Bahrain & KSA reference that contains all of the endpoints. Let’s look at the First Transaction folder. It has all of the calls for a standard e-commerce scenario of creating a customer, charging them, and viewing their resulting transaction. You should be able to run each request in order without any trouble. Relevant IDs in the responses will be automatically added to your environment for subsequent requests. You’ll need to use your API Sandbox credentials to use the testing card nonces.

Tips and Tricks: Code Snippets

The Postman app has the ability to instantly generate code snippets in numerous languages and frameworks, so you can make the same request from your application.

Once you’ve selected an API call, click "Code" on the right, and select your language from the drop-down list.

Authentication APIs

TG uses access tokens to authenticate and authorize API requests. The access token is provided in the HTTP Authorization header as Authorization: Bearer for all end points, and is valid for a limited time.

Generate Access Token

Environment Domain Url
Sandbox https://oauth.tarabutgateway.io/sandbox/
Production https://oauth.tarabutgateway.io/

Authentication API endpoint

Description Endpoint
Fetch access token POST /token

Request Header

Header Key Header Value Notes
Content-Type application/json
X-TG-CustomerUserId <Your unique user
identifier value>		 This value is used to identify your user in our system.
Necessary for establishing the user context of the payment being processed or the account information being retrieved. Not required for guest payment checkout.
Must be less than 40 chars.

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Body

Sample Request

curl --location --request POST 'https://oauth.tarabutgateway.io/sandbox/token' \
--header 'Content-Type: application/json' \
--header 'X-TG-CustomerUserId: <customer_user_id>' \
--data-raw '{
    "clientId": "<your client id>",
    "clientSecret": "<your client secret>",
    "grantType": "client_credentials"
}'

Authentication API endpoint (Old version)

Note: This version of the API will be deprecated soon. Clients should integrate the new version of the API.

Description Endpoint
Fetch access token POST /auth/v1/token

Fetch access token for your authentication and use to access TG APIs

HTTP Request Url

POST /auth/v1/token

Request Header

Header Key Header Value Notes
Content-Type application/json
X-TG-CustomerUserId <Your unique user
identifier value>		 This value is used to identify your user in our system.
Necessary for establishing the user context of the payment being processed or the account information being retrieved. Not required for guest payment checkout.
Must be less than 40 chars.

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Body

Sample Request

curl --location --request POST 'https://api.sandbox.tarabutgateway.io/auth/v1/token' \
--header 'Content-Type: application/json' \
--header 'X-TG-CustomerUserId: <customer_user_id>' \
--data-raw '{
    "clientId": "<your client id>",
    "clientSecret": "<your client secret>",
    "grantType": "client_credentials"
}'

url = "https://api.sandbox.tarabutgateway.io/auth/v1/token"

payload = json.dumps({
  "clientId": "<your client id>",
  "clientSecret": "<your client secret>",
  "grantType": "client_credentials"
})
headers = {
  'Content-Type': 'application/json',
  'X-TG-CustomerUserId': '<customer_user_id>'
}

response = requests.request("POST", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\"clientId\": \"<your client id>\",\n\"clientSecret\": \"<your client secret>\",\n\"grantType\": \"client_credentials\"\n}");
Request request = new Request.Builder()
  .url("https://api.sandbox.tarabutgateway.io/auth/v1/token")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("X-TG-CustomerUserId", "<customer_user_id>")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/auth/v1/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("X-TG-CustomerUserId", "<customer_user_id>");
var body = @"{" + "\n" +
@"""clientId"": ""<your client id>""," + "\n" +
@"""clientSecret"": ""<your client secret>""," + "\n" +
@"""grantType"": ""client_credentials""" + "\n" +
@"}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Field Type Description
clientId string
required		 Your application Client ID. You can get this from TG Console
clientSecret string
required		 Your application Client Secret. You can get this from TG Console
grantType string
required		 "client_credentials" - static value
scopes string Send on the scope in case you want to limit access token use for better security. Multiple scopes can be passed separated by space
redirect_uri string Provide a redirect url here if multiple URLs are configured in the TG console.

Response Fields

Sample Response (200 Success)

{
    "accessToken": "Your_access_token",
    "expiresIn": 3600,
    "tokenType": "Bearer"
}

Returns the accessToken that needs to be used for TG API authentication.

Field Type Description
accessToken string Generated access token that needs to be used for API access in Authorization header
expiresIn integer Validity of Token in seconds
tokenType string "Bearer"

Errors

HTTP Code Error Description
403 INVALID_SCOPES Requested product scope is not available or subscribed for this client id
400 INVALID_API_KEYS Invalid or missing client id or secret provided
403 API_ACCESS_DENIED Client ID suspended/blocked

Note: This section list out summary of specific errors for this API. Refer here for generic errors and more detailed explanation.

Providers

List of financial institutions we provide coverage to across our product offerings. It includes below API :

Description Endpoint
Get Providers GET /v1/providers

Available Financial Institutions

Below API enables you to retrieve list of bank institutions supported by TG.

Request Url

GET /v1/providers

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Sample Request

curl --location --request GET 'https://api.sandbox.tarabutgateway.io/v1/providers' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

import requests
import json

url = "https://api.sandbox.tarabutgateway.io/v1/providers"

headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType = MediaType.parse("application/json");
        Request request = new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/v1/providers")
        .method("GET")
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

Response Fields

Sample Response (200 Success)

{
  "providers": [
    {
      "providerId": "BANKA",
      "name": "BANKA",
      "displayName": "BANKA",
      "logoUrl": "http://BANKA.com",
      "countryCode": "BHR",
      "aisStatus": "UNAVAILABLE",
      "pisStatus": "AVAILABLE"
    },
    {
      "providerId": "BANKB",
      "name": "BANKB",
      "displayName": "BANKB",
      "logoUrl": "http://BANKB.com",
      "countryCode": "BHR",
      "aisStatus": "AVAILABLE",
      "pisStatus": "UNAVAILABLE"
    }
  ]
}
Field Type Description
providerId string Bank's unique id configured at TG.
name string Name of the bank.
displayName string Display name of the bank.
logoUrl string URL to retrieve the logo of the bank.
countryCode string The Country code providerId is registered in.
aisStatus string CONNECT's status eg : AVAILABLE,UNAVAILABLE
pisStatus string PAY's status, eg : AVAILABLE,UNAVAILABLE

AIS/PIS Status

Status Description
AVAILABLE Connect/PAY is supported by TG for the bank
UNAVAILABLE Connect/PAY is not supported at TG for the bank

Connect

Get permissioned access to bank accounts. Retrieve account and enriched transaction data.

Connect APIs include the following endpoints:

Description Endpoint
Create Intent POST /accountInformation/v1/intent
List Accounts GET /accountInformation/v1/accounts
Get Account Holder Name GET /accountInformation/v1/accounts/{accountId}
List Transactions GET /accountInformation/v1/accounts/{accountId}/transactions
List Raw Transactions GET /accountInformation/v1/accounts/{accountId}/rawtransactions

Country Support

Country Support: The environment URLs differ by country.
Ensure to use the correct URL for all requests. Refer Environment URLs section.

Bahrain

Create Intent

POST /accountInformation/v1/intent enables you to have your users initiate the account linking process by creating an intent.

The API should be called from your backend/server and it returns a connect url, which starts the consent journey for an end-user.

Note: An intent is not complete until the user authorises consent to access their account information at their bank.

Request Url

POST /accountInformation/v1/intent

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Body

Sample Request 

curl --location --request POST 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "user":{
    "customerUserId": "7982364", 
    "email": "some@email.com",
    "firstName": "John",
    "lastName": "Snow",
    "userIdentifier": {
      "type": "BH.CPR",
      "value": "332633423"
    }
  },
  "consent":{
    "providerId": "NBOB"
  },
  "redirectUrl": "http://override.me/notDefault"
}'

import requests
import json

url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent"

payload = json.dumps({
  "user": {
    "customerUserId": "7982364",
    "email": "some@email.com",
    "firstName": "John",
    "lastName": "Snow",
    "userIdentifier": {
      "type": "BH.CPR",
      "value": "332633423"
    }
  },
  "consent":{
    "providerId": "NBOB"
  },
  "redirectUrl": "http://override.me/notDefault"
})
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, "{\n  \"user\":{\n    \"customerUserId\": \"7982364\", \n    \"email\": \"some@email.com\",\n    \"firstName\": \"John\",\n    \"lastName\": \"Snow\",\n  \"userIdentifier\": {\n      \"type\": \"BH.CPR\",\n      \"value\": \"332633423\"\n    }\n  },\n  \"redirectUrl\": \"http://override.me/notDefault\",\n  \"consent\":{\n    \"providerId\": \"NBOB\"\n  }\n}");
        Request request = new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent")
        .method("POST", body)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@"  ""user"":{" + "\n" +
@"    ""customerUserId"": ""7982364"", " + "\n" +
@"    ""email"": ""some@email.com""," + "\n" +
@"    ""firstName"": ""John""," + "\n" +
@"    ""lastName"": ""Snow""," + "\n" +
@"    ""userIdentifier"": {" + "\n" +
@"      ""type"": ""BH.CPR""," + "\n" +
@"      ""value"": ""332633423""" + "\n" +
@"    }" + "\n" +
@"  }," + "\n" +
@"  ""consent"":{" + "\n" +
@"    ""providerId"": ""NBOB""" + "\n" +
@"  }," + "\n" +
@"  ""redirectUrl"": ""http://override.me/notDefault""" + "\n" +
@"}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field Type Description
user Object
required		 Developer managed user context
  customerUserId string
required		 Unique user identification managed by TPP. This must match the X-TG-CustomerUserId header value provided when creating the auth token (see Generate Access Token)
Must be less than 40 characters
  email string
optional		 Valid email of the user maintained by TPP (This field is required if 'userIdentifier' is null)
  firstName string
required		 First name of the user
60 characters max
  lastName string
required		 Last name of the user
60 characters max
  userIdentifier Object
optional		 Natural identification of user maintained by TPP (This field is required if 'email' is null)
    type string
required		 One of TG supported national identification schema.
    value string
required		 Value of national identification.
60 characters max
consent Object
optional		 Additional details on the consent
  providerId string
optional		 Unique identification of the provider (see Providers)
Provide this identifier to skip the bank selection screen in the Connect flow.
3 to 8 characters length
redirectUrl string
required		 Redirect URL for the current session (must be a valid https url, including scheme and the one confirgured in TG Console)

Response Fields

Sample Response (200 Success)

{
  "connectUrl": "https://connect.sandbox.tarabutgateway.io/launch/?....",
  "intentId": "092d24cc-4691-460d-a33b-f54f0b26403c",
  "expiry": "2022-04-06T16:30:00Z"
}

connectUrl field must be used to initiate consent journey, which is to authorise and complete the account linking flow.

Once the linking is completed TG will make a callback to the redirect url used during intent creation.

Field Type Description
connectUrl string The url that needs to be invoked to complete the consent authorisation.
intentId string The unique intent ID (generated by TG) for every linking request.
expiry dateTime Expiry of the intent before which the redirect URL has to be used.

A successfulPOST /accountInformation/v1/intent call returns the Connect URL. The Connect URL loads a web view that guides your end user through the consent journey. Users choose their provider and are automatically directed to authenticate and authorise consent.

The Connect journey has the following basic steps -

  1. Select a provider
  2. Review Permissions
  3. Redirect to provider
  4. Authenticate and Authorise at the provider
  5. Redirect to your app

Looking to build your own provider screen?

To skip the provider list, include the providerId in the Create Intent call. This allows the generation of the Connect URL with Step 2 outlined above.

Get Intent

GET /accountInformation/v1/intent/{intentId} enables you to get information about existing intents.

GET /accountInformation/v1/intent/{intentId}

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Path Parameters

Path Parameter Name Type Description
intentId String The ID of the intent.

Sample Request

curl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8"

payload={}
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        Request request = new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8")
        .method("GET", null)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Response Fields

Sample Response (200 Success)

{
  "intentId": "65b56744-719b-4cc7-870d-034b158056c8",
  "providerId": "BLUE",
  "intentStatus": "COMPLETED"
}
Field Type Description
intentId string The ID of the intent.
providerId string Unique identifier to represent a provider/bank.
intentStatus string Status of the intent, e.g. CREATED, INITIATED,CONSENT_INITIATED, CONSENT_REJECTED,COMPLETED, UNKNOWN.

Intent Status

Status Description
CREATED Initial status of the intent
Available post a successful Create Intent call once the Connect URL is generated.
INITIATED Connect URL has been consumed/invoked
CONSENT_INITIATED User is redirected to the provider to authorise consent
CONSENT_REJECTED User rejects consent at the provider
COMPLETED User authorises consent at the provider

List Accounts

GET /accountInformation/v1/accounts enables you to list accounts for the user by providing the required parameters listed below.

Note: Only accounts that have been linked and given consent to be fetched will be listed in the response (see Create Intent).

Request Url

GET /accountInformation/v1/accounts

Request Headers

Sample Request

curl --location --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts"

payload = ""
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json',
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
  .url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts")
  .method("GET", null)
  .addHeader("Authorization", "Bearer <your_access_token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Response Fields

Sample Response (200 Success)

{
  "accounts": [
    {
      "accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
      "accountProductType": "SAVINGS",
      "accountDescription": "John Snow's savings account",
      "providerId": "NBOB",
      "maskedAccountNumber": "******1234",
      "identifiers":[ 
       { 
      "type": "IBAN"
      "value": "string"  
       } 
      ],
      "balances": [
        {
          "type": "AVAILABLE",
          "amount": {
            "value": 123.123,
            "currency": "BHD"
          }
        }
      ],
      "lastUpdatedDateTime": "2021-12-22T01:59:30.208+00:00",
      "links": [
        {
          "rel": "TRANSACTIONS",
          "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions"
        }
      ]
    }
  ]
}
Field Type Description
accounts Object[] Array of account objects for a given account.
  accountId string Unique account ID (generated by TG) for every account that is linked.
  accountProductType string Type of account product, e.g. SAVINGS, CURRENT, DEPOSIT, CREDIT_CARD, CHARGE_CARD.
  accountDescription string Description of the account (supplied by the bank).
  providerId string Unique identifier to represent a provider/bank.
  maskedAccountNumber string Masked account number from the bank, with only last four digits shown.
  identifiers Object[] Coming soon
Array of account identifiers provided by the bank. This may include IBAN, maskedPAN
    type string Type of identifier- IBAN, maskedPAN
    value string Identifier value.
  balances Object[] Array of account balance objects.
    type string Account balance type, e.g. AVAILABLE, OUTSTANDING.
    amount Money Account balance amount.
  lastUpdatedDateTime string Timestamp of when the account was last updated in DateTime format.
  links Link[] Array of Link objects for granular account details, e.g. TRANSACTIONS.

Get Account Holder Name

GET /accountInformation/v1/accounts/{accountId} enables you to fetch account holder name for a given account id.

Note: Only accounts that have been linked and given consent to be fetched will be listed in the response (see Create Intent).

Request Url

GET /accountInformation/v1/accounts/{accountId}

Request Headers

Sample Request

curl --location --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}"

payload = ""
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json',
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
  .url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}")
  .method("GET", null)
  .addHeader("Authorization", "Bearer <your_access_token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Response Fields

Sample Response (200 Success)

{
      "accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
      "accountHolderName": "Mohammed Ahmed Abdulla",
      "nickname": "Abdulla"
}
Field Type Description
accountId string Unique account ID (generated by TG) for every account that is linked. The identifier is returned in List Accounts response.
accountHolderName string Comma separated list of full names of the account holder. In case of a joint account, it will include all account holder names.
nickname string Nickname.

List Account Transactions

GET /accountInformation/v1/accounts/{accountId}/transactions enables you to fetch transactions for a given account ID by providing the required parameters listed below.

Request Url

GET /accountInformation/v1/accounts/{accountId}/transactions

Request Header

Header Key Header Value Notes
Content-Type application/json
Authorization Bearer <your_access_token> Token will contain the user identifier

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Parameters

Parameter Name Type Description
page Integer
optional		 Desired results page number (defaults to 1).
fromBookingDateTime string
optional		 Start timestamp for transaction request in DateTime format.
toBookingDateTime string
optional		 End timestamp for transaction request in DateTime format.

Request Path Parameters

Path Parameter Name Type Description
accountId string
required		 TG account ID to request transactions for.
The identifier is returned in List Accounts response.

Sample Request

curl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4"

payload={}
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        Request request = new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4")
        .method("GET", null)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Response Fields

Sample Response (200 Success)

{
  "transactions": [
    {
      "transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
      "accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
      "providerId": "NBOB",
      "transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
      "category": {
        "group": "Expense",
        "name": "Entertainment & Leisure"
      },
      "merchant": {
        "name": "NETFLIX.COM"
      },
      "creditDebitIndicator": "DEBIT",
      "amount": {
        "value": 14.99,
        "currency": "BHD"
      },
      "bookingDateTime": "2021-12-22T01:59:30.208+00:00"
    }
  ],
  "meta": {
    "totalCountOfRecords": 100,
    "totalCountOfPages": 10,
    "pageNumber": 4,
    "pageSize": 10
  },
  "links": [
    {
      "rel": "FIRST",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=1"
    },
    {
      "rel": "PREVIOUS",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=3"
    },
    {
      "rel": "NEXT",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=5"
    },
    {
      "rel": "LAST",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=10"
    }
  ]
}

Note: In the sample response JSON, the pagination Meta object indicates that there are 10 records per page (pageSize). Only one transaction is shown here in order to keep this example response as succinct as possible.

Field Type Description
transactions Object[] Array of transaction objects for a given account.
  transactionId string Unique transaction ID (generated by TG) for every transaction.
  accountId string Account ID that the transaction is linked to (provided as path parameter).
  providerId string Unique identifier to represent a provider/bank.
  transactionDescription string Description of the transaction provided by the bank.
  category Object Internally generated category object for the transaction.
    group string Top level category group.
enum: Category Group
    name string Main category name.
enum: Categories
  merchant Object
nullable		 Internally generated merchant object for the transaction.
    name string Name of the merchant in the transaction.
  creditDebitIndicator string Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT.
  amount Money Transaction amount.
  bookingDateTime string Timestamp of when the transaction was booked in DateTime format.
meta Object[] Pagination and query metadata object.
  fromBookingDateTime string Start timestamp for transaction request in DateTime format.
  toBookingDateTime string End timestamp for transactions request in DateTime format.
  totalCountOfRecords Integer Total count of records.
  totalCountOfPages Integer Total count of pages for the given page size.
  pageNumber Integer Current page number.
  pageSize Integer Number of records returned per page.
links Link[] Array of Link objects for pagination, e.g. FIRST, LAST, PREVIOUS, NEXT.

List Account Raw Transactions

GET /accountInformation/v1/accounts/{accountId}/rawtransactions enables you to fetch transactions for a given account ID that have not been enriched by providing the required parameters listed below.

Request Header

Header Key Header Value Notes
Content-Type application/json
Authorization Bearer <your_access_token> Token will contain the user identifier

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Url

GET /accountInformation/v1/accounts/{accountId}/rawtransactions

Request Parameters

Parameter Name Type Description
page Integer
optional		 Desired results page number (defaults to 1).
fromBookingDateTime string
optional		 Start timestamp for transaction request in DateTime format.
toBookingDateTime string
optional		 End timestamp for transaction request in DateTime format.

Request Path Parameters

Path Parameter Name Type Description
accountId string
required		 TG account ID to request transactions for.

Sample Request

curl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4"

payload={}
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        Request request = new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4")
        .method("GET", null)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Response Fields

Sample Response (200 Success)

{
  "transactions": [
    {
      "transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
      "accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
      "providerId": "NBOB",
      "transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
      "creditDebitIndicator": "DEBIT",
      "amount": {
        "value": 14.99,
        "currency": "BHD"
      },
      "bookingDateTime": "2021-12-22T01:59:30.208+00:00"
    }
  ],
  "meta": {
    "totalCountOfRecords": 100,
    "totalCountOfPages": 10,
    "pageNumber": 4,
    "pageSize": 10
  },
  "links": [
    {
      "rel": "FIRST",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=1"
    },
    {
      "rel": "PREVIOUS",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=3"
    },
    {
      "rel": "NEXT",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=5"
    },
    {
      "rel": "LAST",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=10"
    }
  ]
}

Note: In the sample response JSON, the pagination Meta object indicates that there are 10 records per page (pageSize), however we have only shown one transaction here in order to keep this example response as succinct as possible.

Field Type Description
transactions Object[] Array of transaction objects for a given account.
  transactionId string Unique transaction ID (generated by TG) for every transaction.
  accountId string Account ID that the transaction is linked to (provided as path parameter).
  providerId string Unique identifier to represent a provider/bank.
  transactionDescription string Description of the transaction provided by the bank.
  creditDebitIndicator string Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT.
  amount Money Transaction amount.
  bookingDateTime string Timestamp of when the transaction was booked in DateTime format.
meta Object[] Pagination and query metadata object.
  fromBookingDateTime string Start timestamp for transaction request in DateTime format.
  toBookingDateTime string End timestamp for transactions request in DateTime format.
  totalCountOfRecords Integer Total count of records.
  totalCountOfPages Integer Total count of pages for the given page size.
  pageNumber Integer Current page number.
  pageSize Integer Number of records returned per page.
links Link[] Array of Link objects for pagination, e.g. FIRST, LAST, PREVIOUS, NEXT.

Saudi Arabia

Get permissioned access to bank accounts. Retrieve account and enriched transaction data.

Connect APIs include the following endpoints:

Description Endpoint
Create Intent POST /accountInformation/v1/intent
List Accounts GET /accountInformation/v1/accounts
Get Account Holder Name GET /accountInformation/v1/accounts/{accountId}
List Transactions GET /accountInformation/v1/accounts/{accountId}/transactions
List Raw Transactions GET /accountInformation/v1/accounts/{accountId}/rawtransactions

Country Support

Country Support: The environment URLs differ by country.
Ensure to use the correct URL for all requests. Refer Environment URLs section.

Create Intent

POST /accountInformation/v1/intent enables you to have your users initiate the account linking process by creating an intent.

The API should be called from your backend/server and it returns a connect url, which starts the consent journey for an end-user.

Note: An intent is not complete until the user authorises consent to access their account information at their bank.

Request Url

POST /accountInformation/v1/intent

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Body

Sample Request shell curl --location --request POST 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent' \ --header 'Authorization: Bearer <your_access_token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "user": { "customerUserId": "7982364", "email": "some@email.com "firstName": "John", "lastName": "Snow", }, "consent":{ "providerId": "SNB" }, "redirectUrl": "http://override.me/notDefault" }' 

import requests
import json

url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent"

payload = json.dumps({
  "user": {
    "customerUserId": "7982364",
    "email": "some@email.com",
    "firstName": "John",
    "lastName": "Snow"
  },
  "consent":{
    "providerId": "NBOB"
  },
  "redirectUrl": "http://override.me/notDefault"
})
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, "{\n  \"user\":{\n    \"customerUserId\": \"7982364\", \n    \"email\": \"some@email.com\",\n    \"firstName\": \"John\",\n    \"lastName\": \"Snow\",\n  \"userIdentifier\": {\n      \"type\": \"BH.CPR\",\n      \"value\": \"332633423\"\n    }\n  },\n  \"redirectUrl\": \"http://override.me/notDefault\",\n  \"consent\":{\n    \"providerId\": \"NBOB\"\n  }\n}");
        Request request = new Request.Builder()
        .url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent")
        .method("POST", body)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@"  ""user"":{" + "\n" +
@"    ""customerUserId"": ""7982364"", " + "\n" +
@"    ""email"": ""some@email.com""," + "\n" +
@"    ""firstName"": ""John""," + "\n" +
@"    ""lastName"": ""Snow""," + "\n" +
@"    ""userIdentifier"": {" + "\n" +
@"      ""type"": ""BH.CPR""," + "\n" +
@"      ""value"": ""332633423""" + "\n" +
@"    }" + "\n" +
@"  }," + "\n" +
@"  ""consent"":{" + "\n" +
@"    ""providerId"": ""NBOB""" + "\n" +
@"  }," + "\n" +
@"  ""redirectUrl"": ""http://override.me/notDefault""" + "\n" +
@"}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field Type Description
user Object
required		 Developer managed user context
  customerUserId string
required		 Unique user identification managed by TPP. This must match the X-TG-CustomerUserId header value provided when creating the auth token (see Generate Access Token)
Must be less than 40 characters
  email string
optional		 Valid email of the user maintained by TPP (This field is required if 'userIdentifier' is null)
  firstName string
required		 First name of the user
60 characters max
  lastName string
required		 Last name of the user
60 characters max
consent Object
optional		 Additional details on the consent
  providerId string
optional		 Unique identification of the provider (see Available Providers)
Provide this identifier to skip the bank selection screen in the Connect flow.
3 to 8 characters length
redirectUrl string
required		 Redirect URL for the current session (must be a valid https url, including scheme and the one configured in TG Developer Portal)

Response Fields

Sample Response (200 Success)

{
  "connectUrl": "https://connect.sau.tarabutgateway.io/launch/?.....",
  "intentId": "092d24cc-4691-460d-a33b-f54f0b26403c",
  "expiry": "2022-04-06T16:30:00Z"
}

connectUrl field must be used to initiate consent journey, which is to authorise and complete the account linking flow.

Once the linking is completed TG will make a callback to the redirect url used during intent creation.

Field Type Description
connectUrl string The url that needs to be invoked to complete the consent authorisation.
intentId string The unique intent ID (generated by TG) for every linking request.
expiry dateTime Expiry of the intent before which the redirect URL has to be used.

A successfulPOST /accountInformation/v1/intent call returns the Connect URL. The Connect URL loads a web view that guides your end user through the consent journey. Users choose their provider and are automatically directed to authenticate and authorise consent.

The Connect journey has the following basic steps -

  1. Select a provider
  2. Review Permissions
  3. Redirect to provider
  4. Authenticate and Authorise at the provider
  5. Redirect to your app

Looking to build your own provider screen?

To skip the provider list, include the providerId in the Create Intent call. This allows the generation of the Connect URL with Step 2 outlined above.

Get Intent

GET /accountInformation/v1/intent/{intentId} enables you to get information about existing intents.

GET /accountInformation/v1/intent/{intentId}

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Path Parameters

Path Parameter Name Type Description
intentId String The ID of the intent.

Sample Request 

curl --location -g --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8"

payload={}
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        Request request = new Request.Builder()
        .url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8")
        .method("GET", null)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Response Fields

Sample Response (200 Success)

{
  "intentId": "65b56744-719b-4cc7-870d-034b158056c8",
  "providerId": "BLUE",
  "intentStatus": "COMPLETED"
}
Field Type Description
intentId string The ID of the intent.
providerId string Unique identifier to represent a provider/bank.
intentStatus string Status of the intent, e.g. CREATED, INITIATED,CONSENT_INITIATED, CONSENT_REJECTED,COMPLETED, UNKNOWN.

Intent Status

Status Description
CREATED Initial status of the intent
Available post a successful Create Intent call once the Connect URL is generated.
INITIATED Connect URL has been consumed/invoked
CONSENT_INITIATED User is redirected to the provider to authorise consent
CONSENT_REJECTED User rejects consent at the provider
COMPLETED User authorises consent at the provider

List Accounts

GET /accountInformation/v1/accounts enables you to list accounts for the user by providing the required parameters listed below.

Note: Only accounts that have been linked and given consent to be fetched will be listed in the response (see Create Intent).

Request Url

GET /accountInformation/v1/accounts

Request Headers

Sample Request

curl --location --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts"

payload = ""
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json',
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
  .url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts")
  .method("GET", null)
  .addHeader("Authorization", "Bearer <your_access_token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Response Fields

Sample Response (200 Success)

{
  "accounts": [
    {
      "accountId": "6549b0dd-27a1-3f5b-ab2a-9a83d8245d16",
      "accountProductType": "SAVINGS",
      "accountDescription": "John Doe - SAR Savings",
      "providerId": "BLUE",
      "maskedAccountNumber": "******************8527",
      "identifiers":[ 
       { 
      "type": "IBAN"
      "value": "string"  
       } 
      ],
      "balances": [
        {
          "type": "AVAILABLE",
          "amount": {
            "value": 123.13,
            "currency": "SAR"
          }
        }
      ],
      "lastUpdatedDateTime": "2021-12-22T01:59:30.208+00:00",
      "links": [
        {
          "rel": "TRANSACTIONS",
          "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/6549b0dd-27a1-3f5b-ab2a-9a83d8245d16/transactions"
        }
      ]
    }
  ]
}
Field Type Description
accounts Object[] Array of account objects for a given account.
  accountId string Unique account ID (generated by TG) for every account that is linked.
  accountProductType string Type of account product, e.g. SAVINGS, CURRENT, DEPOSIT, CREDIT_CARD, CHARGE_CARD.
  accountDescription string Description of the account (supplied by the bank).
  providerId string Unique identifier to represent a provider/bank.
  maskedAccountNumber string Masked account number from the bank, with only last four digits shown.
  identifiers Object[] Coming soon
Array of account identifiers provided by the bank. This may include IBAN, maskedPAN
    type string Type of identifier- IBAN, maskedPAN
    value string Identifier value.
  balances Object[] Array of account balance objects.
    type string Account balance type, e.g. AVAILABLE, OUTSTANDING.
    amount Money Account balance amount.
  lastUpdatedDateTime string Timestamp of when the account was last updated in DateTime format.
  links Link[] Array of Link objects for granular account details, e.g. TRANSACTIONS.

Get Account Holder Name

GET /accountInformation/v1/accounts/{accountId} enables you to fetch account holder name for a given account id.

Note: Only accounts that have been linked and given consent to be fetched will be listed in the response (see Create Intent).

Request Url

GET /accountInformation/v1/accounts/{accountId}

Request Headers

Sample Request

curl --location --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}"

payload = ""
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json',
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
  .url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}")
  .method("GET", null)
  .addHeader("Authorization", "Bearer <your_access_token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the user identifier
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Response Fields

Sample Response (200 Success)

{
      "accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
      "accountHolderName": "Mohammed Ahmed Abdulla",
      "nickname": "Abdulla"
}
Field Type Description
accountId string Unique account ID (generated by TG) for every account that is linked. The identifier is returned in List Accounts response.
accountHolderName string Comma separated list of full names of the account holder. In case of a joint account, it will include all account holder names.
nickname string Nickname.

List Account Transactions

GET /accountInformation/v1/accounts/{accountId}/transactions enables you to fetch transactions for a given account ID by providing the required parameters listed below.
All transactions are enriched with enriched attributes from TG's Insights service that provides category and merchant details. Find details of categorisation and merchant enrichment here.

Request Url

GET /accountInformation/v1/accounts/{accountId}/transactions

Request Header

Header Key Header Value Notes
Content-Type application/json
Authorization Bearer <your_access_token> Token will contain the user identifier

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Parameters

Parameter Name Type Description
page Integer
optional		 Desired results page number (defaults to 1).
fromBookingDateTime string
optional		 Start timestamp for transaction request in DateTime format.
toBookingDateTime string
optional		 End timestamp for transaction request in DateTime format.

Request Path Parameters

Path Parameter Name Type Description
accountId string
required		 TG account ID to request transactions for.
The identifier is returned in List Accounts response.

Sample Request

curl --location -g --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4"

payload={}
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        Request request = new Request.Builder()
        .url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4")
        .method("GET", null)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Response Fields

Sample Response (200 Success)

{
  "transactions": [
    {
      "transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
      "accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
      "providerId": "NBOB",
      "transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
      "category": {
        "group": "Expense",
        "name": "Entertainment & Leisure"
      },
      "merchant": {
        "name": "NETFLIX.COM"
      },
      "creditDebitIndicator": "DEBIT",
      "amount": {
        "value": 14.99,
        "currency": "BHD"
      },
      "bookingDateTime": "2021-12-22T01:59:30.208+00:00"
    }
  ],
  "meta": {
    "totalCountOfRecords": 100,
    "totalCountOfPages": 10,
    "pageNumber": 4,
    "pageSize": 10
  },
  "links": [
    {
      "rel": "FIRST",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=1"
    },
    {
      "rel": "PREVIOUS",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=3"
    },
    {
      "rel": "NEXT",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=5"
    },
    {
      "rel": "LAST",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=10"
    }
  ]
}

Note: In the sample response JSON, the pagination Meta object indicates that there are 10 records per page (pageSize). Only one transaction is shown here in order to keep this example response as succinct as possible.

Field Type Description
transactions Object[] Array of transaction objects for a given account.
  transactionId string Unique transaction ID (generated by TG) for every transaction.
  accountId string Account ID that the transaction is linked to (provided as path parameter).
  providerId string Unique identifier to represent a provider/bank.
  transactionDescription string Description of the transaction provided by the bank.
  category Object Internally generated category object for the transaction.
    group string Top level category group.
enum: Category Group
    name string Main category name.
enum: Categories
  merchant Object
nullable		 Internally generated merchant object for the transaction.
    name string Name of the merchant in the transaction.
  creditDebitIndicator string Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT.
  amount Money Transaction amount.
  bookingDateTime string Timestamp of when the transaction was booked in DateTime format.
meta Object[] Pagination and query metadata object.
  fromBookingDateTime string Start timestamp for transaction request in DateTime format.
  toBookingDateTime string End timestamp for transactions request in DateTime format.
  totalCountOfRecords Integer Total count of records.
  totalCountOfPages Integer Total count of pages for the given page size.
  pageNumber Integer Current page number.
  pageSize Integer Number of records returned per page.
links Link[] Array of Link objects for pagination, e.g. FIRST, LAST, PREVIOUS, NEXT.

List Account Raw Transactions

GET /accountInformation/v1/accounts/{accountId}/rawtransactions enables you to fetch transactions for a given account ID that have not been enriched by providing the required parameters listed below.

Request Header

Header Key Header Value Notes
Content-Type application/json
Authorization Bearer <your_access_token> Token will contain the user identifier

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Url

GET /accountInformation/v1/accounts/{accountId}/rawtransactions

Request Parameters

Parameter Name Type Description
page Integer
optional		 Desired results page number (defaults to 1).
fromBookingDateTime string
optional		 Start timestamp for transaction request in DateTime format.
toBookingDateTime string
optional		 End timestamp for transaction request in DateTime format.

Request Path Parameters

Path Parameter Name Type Description
accountId string
required		 TG account ID to request transactions for.

Sample Request

curl --location -g --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4"

payload={}
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        Request request = new Request.Builder()
        .url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4")
        .method("GET", null)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Response Fields

Sample Response (200 Success)

{
  "transactions": [
    {
      "transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
      "accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
      "providerId": "NBOB",
      "transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
      "creditDebitIndicator": "DEBIT",
      "amount": {
        "value": 14.99,
        "currency": "BHD"
      },
      "bookingDateTime": "2021-12-22T01:59:30.208+00:00"
    }
  ],
  "meta": {
    "totalCountOfRecords": 100,
    "totalCountOfPages": 10,
    "pageNumber": 4,
    "pageSize": 10
  },
  "links": [
    {
      "rel": "FIRST",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=1"
    },
    {
      "rel": "PREVIOUS",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=3"
    },
    {
      "rel": "NEXT",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=5"
    },
    {
      "rel": "LAST",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=10"
    }
  ]
}

Note: In the sample response JSON, the pagination Meta object indicates that there are 10 records per page (pageSize), however we have only shown one transaction here in order to keep this example response as succinct as possible.

Field Type Description
transactions Object[] Array of transaction objects for a given account.
  transactionId string Unique transaction ID (generated by TG) for every transaction.
  accountId string Account ID that the transaction is linked to (provided as path parameter).
  providerId string Unique identifier to represent a provider/bank.
  transactionDescription string Description of the transaction provided by the bank.
  creditDebitIndicator string Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT.
  amount Money Transaction amount.
  bookingDateTime string Timestamp of when the transaction was booked in DateTime format.
meta Object[] Pagination and query metadata object.
  fromBookingDateTime string Start timestamp for transaction request in DateTime format.
  toBookingDateTime string End timestamp for transactions request in DateTime format.
  totalCountOfRecords Integer Total count of records.
  totalCountOfPages Integer Total count of pages for the given page size.
  pageNumber Integer Current page number.
  pageSize Integer Number of records returned per page.
links Link[] Array of Link objects for pagination, e.g. FIRST, LAST, PREVIOUS, NEXT.

Insights

Accepts a list of raw transactions and returns transactions enriched with category and merchant.

Supported APIs are given below

Description Endpoint
Enrich transactions POST /ingest/v1/enrich
Fetch salaries GET /insights/v1/salary
Identify salaries POST /ingest/v1/salary

Enrich Transactions

POST /ingest/v1/enrich enables you to have your users transactions enriched with merchant and category.

The API should be called from your backend/server and it returns a list of the requested transactions and enrichment information.

Works with - Coming Soon

Request Url

POST /ingest/v1/enrich

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the enrich: category and enrich: merchant scopes
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Body

Sample Request

curl --location --request POST 'https://api.sandbox.tarabutgateway.io/ingest/v1/enrich' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {valid-tg-token}' \
--data-raw '{
  "transactions": [
    {
      "transactionId": "1",
      "transactionDescription": "KHCB Lulu Hyper HIDD BH",
      "amount": {
        "value": 14.900,
        "currency": "BHD"
      },
      "creditDebitIndicator": "Credit",
      "transactionDateTime": "2021-12-22T01:59:30.208+00:00"
    },
    {
      "transactionId": "2",
      "transactionDescription": "PURCHASE         ALJAZIRA SUPERMARKET",
      "amount": {
        "value": 3.750,
        "currency": "BHD"
      },
      "creditDebitIndicator": "Credit",
      "transactionDateTime": "2021-12-22T01:00:30.208+00:00"
    }
  ],
  "accountId": "BH62BLUE00200000008527",
  "accountProductType": "account",
  "providerId": "KHCB"
}'

import requests
import json

url = "https://api.sandbox.tarabutgateway.io/ingest/v1/enrich"

payload = json.dumps({
    "transactions": [
        {
            "transactionId": "1",
            "transactionDescription": "KHCB Lulu Hyper HIDD BH",
            "amount": {
                "value": 14.900,
                "currency": "BHD"
            },
            "creditDebitIndicator": "Credit",
            "transactionDateTime": "2021-12-22T01:59:30.208+00:00"
        },
        {
            "transactionId": "2",
            "transactionDescription": "PURCHASE         ALJAZIRA SUPERMARKET",
            "amount": {
                "value": 3.750,
                "currency": "BHD"
            },
            "creditDebitIndicator": "Credit",
            "transactionDateTime": "2021-12-22T01:00:30.208+00:00"
        }
    ],
    "accountId": "BH62BLUE00200000008527",
    "accountProductType": "account",
    "providerId": "KHCB"
})
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, "{\n    \"transactions\": [\n        {\n            \"transactionId\": \"1\",\n            \"transactionDescription\": \"KHCB Lulu Hyper HIDD BH\",\n            \"amount\": {\n                \"value\": 14.900,\n                \"currency\": \"BHD\"\n            },\n            \"creditDebitIndicator\": \"Credit\",\n            \"transactionDateTime\": \"2021-12-22T01:59:30.208+00:00\"\n        },\n        {\n            \"transactionId\": \"2\",\n            \"transactionDescription\": \"PURCHASE         ALJAZIRA SUPERMARKET\",\n            \"amount\": {\n                \"value\": 3.750,\n                \"currency\": \"BHD\"\n            },\n            \"creditDebitIndicator\": \"Credit\",\n            \"transactionDateTime\": \"2021-12-22T01:00:30.208+00:00\"\n        }\n    ],\n    \"accountId\": \"BH62BLUE00200000008527\",\n    \"accountProductType\": \"account\",\n    \"providerId\": \"KHCB\"\n}");
        Request request = new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/ingest/v1/enrich")
        .method("POST", body)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/ingest/v1/enrich");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@"  ""transactions"":[" + "\n" +
@"    {" + "\n" +
@"      ""transactionId"": ""1"", " + "\n" +
@"      ""transactionDescription"": ""KHCB Lulu Hyper HIDD BH""," + "\n" +
@"      ""amount"": {" + "\n" +
@"        ""value"": "14.900"," + "\n" +
@"        ""currency"": ""BHD""" + "\n" +
@"      }" + "\n" +
@"      ""creditDebitIndicator"": ""Credit""," + "\n" +
@"      ""transactionDateTime"": ""2021-12-22T01:59:30.208+00:00""," + "\n" +
@"    }," + "\n" +
@"    {" + "\n" +
@"      ""transactionId"": ""2"", " + "\n" +
@"      ""transactionDescription"": ""PURCHASE         ALJAZIRA SUPERMARKET""," + "\n" +
@"      ""amount"": {" + "\n" +
@"        ""value"": "3.750"," + "\n" +
@"        ""currency"": ""BHD""" + "\n" +
@"      }" + "\n" +
@"      ""creditDebitIndicator"": ""Credit""," + "\n" +
@"      ""transactionDateTime"": ""2021-12-22T01:00:30.208+00:00""," + "\n" +
@"    }" + "\n" +
@"  ]," + "\n" +
@"  ""accountId"": ""BH62BLUE00200000008527""" + "\n" +
@"  ""accountProductType"": ""account""" + "\n" +
@"  ""providerId"": ""KHCB""" + "\n" +
@"}"; 
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field Type Description
transactions Array
required		 List of raw transactions
  transactionId string
required		 Unique identifier of the transaction
  transactionDescription string
required		 Description of the transaction
  amount Object
required		 Information about the amount of the transaction
    value string
required		 Value of the transaction
    currency string
required		 Currency of the transaction
  creditDebitIndicator string
required		 Indicates whether the transaction type is Credit or Debit
  transactionDateTime dateTime
optional		 Date and time that the transaction took place
  accountId string
required		 Unique identifier of the user account
  accountProductType string
required		 Indicates the type of account. Takes 'account' or 'card'
  providerId string
required		 Unique identification of the provider (see Available Providers)
3 to 8 characters length

Response Fields

Sample Response (200 Success)

[
  {
    "transactionId": "1",
    "categorisation":
    {
      "group":"Expense",
      "category":"Groceries"
    },
    "merchantName":"KHCB LULU HYPER HIDD",
    "transactionType":"merchant"
  },
  {
    "transactionId": "2",
    "categorisation":
    {
      "group":"Expense",
      "category":"Groceries"
    },
    "merchantName":"ALJAZIRA SUPERMARKET",
    "transactionType":"merchant"
  }
]
Field Type Description
transactionId string Unique identifier of the transaction.
categorisation Object Categorisation information of the transaction.
  group string Categorisation group of the transaction.
  category string Categorisation category of the transaction.
merchantName string Merchant name for the transaction.
transactionType string Type of transaction.

Available Providers

The table below details available providers by ID and name.

Provider ID Provider Name
ABIB Al Baraka Islamic Bank
ALSA Al Salam Bank
BBKU Bank of Bahrain and Kuwait
BIBB Bahrain Islamic Bank
BLUE Blue Bank *
ESKB Eskan Bank
ABCO Arab Banking Corporation
FIBH Ithmaar Bank
KFHO Kuwait Finance House (Bahrain)
KHCB Khaleeji Commercial Bank
NBOB National Bank of Bahrain
NBOK National Bank of Kuwait
SCBL Standard Chartered Bank

*Blue Bank is a demo provider only available in Sandbox.

Fetch salaries

GET /insights/v1/salary enables you to fetch salaries for a given user, for the last 3 months.

This API should be called from your backend/server and it returns a list of salary amounts with bookingDateTime and month.

Works with - insights.salary:list

Request Url

GET /insights/v1/salary

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the insights.salary:list scope

Request Path Parameters

Path Parameter Name Type Description
months Integer
optional		 Number of months back from which we want transactions.(defaults to 3, and can range from 1 to 6 months)

Note: In addition to the above, also include other headers as documented in Request Headers section

Sample Request

curl --location --request GET 'https://api.sandbox.tarabutgateway.io/insights/v1/salary?months=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {valid-tg-token}' 

import requests
import json

url = "https://api.sandbox.tarabutgateway.io/insights/v1/salary?months=3"

headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType = MediaType.parse("application/json");
        Request request = new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/insights/v1/salary?months=3")
        .method("GET")
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/insights/v1/salary?months=3");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Response Fields

Sample Response (200 Success)

{
  "salaries" : [
    {
    "salaryAmount": {
        "value": "400.0",
        "currency":"BHD"
      },
      "bookingDateTime": "2022-10-01T00:00:00.000Z",
      "monthIndicator": 10
    },
    {
    "salaryAmount": {
        "value": "405.0",
        "currency":"BHD"
      },
      "bookingDateTime": "2022-09-01T00:00:00.000Z",
      "monthIndicator": 9
    },
    {
    "salaryAmount": {
        "value": "410.0",
        "currency":"BHD"
      }, 
     "bookingDateTime": "2022-08-01T00:00:00.000Z",
      "monthIndicator": 8
    }
  ]
}
Field Type Description
salaries Object[] Array of Salary objects for a given user.
  salaryAmount Money Salary amount.
  bookingDateTime string Timestamp of when the transaction was booked in DateTime format.
  monthIndicator Integer Month of salary credit. The value for this field starts from 1(1 = January).

Identify salaries

POST /ingest/v1/salary enables you to identify salary transactions from a list of transactions

This API should be called from your backend/server and it returns a list of salary amounts with bookingDateTime and month.

Works with - insights.salary:list

Request Url

POST /ingest/v1/salary

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token> Token will contain the insights.salary:list scope
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Body

Sample Request

curl --location --request POST 'https://api.sandbox.tarabutgateway.io/ingest/v1/salary' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {valid-tg-token}' \
--data-raw '{
  "accountId": "1028374082309",
  "accountType": "account",
  "providerId": "BLUE",
  "transactions": [
    {
      "transactionId": "100",
      "description": "A SALARY FOR SOMEONE",
      "amount": {
        "value": 500,
        "currency": "BHD"
      },
      "bookingDateTime": "2023-06-28T11:11:30Z",
      "creditDebitIndicator": "Credit"
    },
    {
      "transactionId": "101",
      "description": "Fund transfer from XXXX",
      "amount": {
        "value": 47,
        "currency": "BHD"
      },
      "bookingDateTime": "2023-06-29T10:00:00Z",
      "creditDebitIndicator": "Credit"
    }    
  ]
}'

import requests
import json

url = "https://api.sandbox.tarabutgateway.io/ingest/v1/salary"

payload = json.dumps({
    "accountId": "1028374082309",
    "accountType": "account",
    "providerId": "BLUE",
    "transactions": [
        {
            "transactionId": "100",
            "description": "A SALARY FOR SOMEONE",
            "amount": {
                "value": 500,
                "currency": "BHD"
            },
            "bookingDateTime": "2023-06-28T11:11:30Z",
            "creditDebitIndicator": "Credit"
        },
        {
            "transactionId": "101",
            "description": "Fund transfer from XXXX",
            "amount": {
                "value": 47,
                "currency": "BHD"
            },
            "bookingDateTime": "2023-06-29T10:00:00Z",
            "creditDebitIndicator": "Credit"
        }
    ]
})
headers = {
  'Authorization': 'Bearer <your_access_token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, "{\"accountId\": \"1028374082309\", \"accountType\": \"account\", \"providerId\": \"BLUE\", \"transactions\": [{\"transactionId\": \"100\", \"description\": \"A SALARY FOR SOMEONE\", \"amount\": {\"value\": 500, \"currency\": \"BHD\"}, \"bookingDateTime\": \"2023-06-28T11:11:30Z\", \"creditDebitIndicator\": \"Credit\"}, {\"transactionId\": \"101\", \"description\": \"Fund transfer from XXXX\", \"amount\": {\"value\": 47, \"currency\": \"BHD\"}, \"bookingDateTime\": \"2023-06-29T10:00:00Z\", \"creditDebitIndicator\": \"Credit\"}]}");
        Request request = new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/ingest/v1/salary")
        .method("POST", body)
        .addHeader("Authorization", "Bearer <your_access_token>")
        .addHeader("Content-Type", "application/json")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/ingest/v1/salary");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @""{\"accountId\": \"1028374082309\", \"accountType\": \"account\", \"providerId\": \"BLUE\", \"transactions\": [{\"transactionId\": \"100\", \"description\": \"A SALARY FOR SOMEONE\", \"amount\": {\"value\": 500, \"currency\": \"BHD\"}, \"bookingDateTime\": \"2023-06-28T11:11:30Z\", \"creditDebitIndicator\": \"Credit\"}, {\"transactionId\": \"101\", \"description\": \"Fund transfer from XXXX\", \"amount\": {\"value\": 47, \"currency\": \"BHD\"}, \"bookingDateTime\": \"2023-06-29T10:00:00Z\", \"creditDebitIndicator\": \"Credit\"}]}"; 
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field Type Description
accountId string
required		 Unique identifier of the user account
accountType string
required		 Indicates the type of account. Takes 'account' or 'card'
providerId string
required		 Unique identification of the provider (see Available Providers)
3 to 8 characters length
transactions Array
required		 List of raw transactions
  transactionId string
required		 Unique identifier of the transaction
  description string
required		 Description of the transaction
  amount Object
required		 Information about the amount of the transaction
    value string
required		 Value of the transaction
    currency string
required		 Currency of the transaction
  creditDebitIndicator string
required		 Indicates whether the transaction type is Credit or Debit
  bookingDateTime dateTime
optional		 Date and time that the transaction took place

Response Fields

Sample Response (200 Success)

{
    "accountId": "1028374082309",
    "providerId": "BLUE",
    "transactions": [
        {
            "transactionId": "100",
            "amount": {
                "value": "500.000",
                "currency": "BHD"
            },
            "monthIndicator": 6,
            "bookingDateTime": "2023-06-28T11:11:30.000Z"
        }
    ]
}
Field Type Description
accountId string Unique identifier of the user account
providerId string Unique identification of the provider (see Available Providers)
3 to 8 characters length
transactions Array
 List of identified salary transactions
  transactionId string
 Unique identifier of the transaction
  amount Object
 Information about the amount of the transaction
    value string
 Value of the transaction
    currency string
 Currency of the transaction
  monthIndicator string
 Corresponding month of identified salary
  bookingDateTime dateTime
 Date and time that the transaction took place

Payment Initiation

Initiate secure bank to bank payments using TG's Payment Initiation capabilities. Use the APIs below on TG Pay to create an end-to-end payment experience.

Description Endpoint
Initiate a payment request POST /paymentInitiation/v1/payments
Fetch payment status GET /paymentInitiation/v1/payments/{paymentId}

Initiate Payment

`Making a POST call to this API enables you to initiate a payment for a given user by providing the required parameters listed below. The API should be called from your backend/server. The response contains a paymentURL and a paymentId for the user to authorise the requested payment.

🇧🇭 In Bahrain

Our service can be used to initiate a Single Domestic Payment via Fawri+. Fawri+ settles transactions in near real-time, up to 30 seconds and are limited to 1000.000 BHD. Other payment types of payment rails, like Fawri, a slower delayed settlement payment method, are currently not supported. TG does not support other payment types, like future-dated and international payments.

🇸🇦 In The Kingdom of Saudi Arabia Payments are not yet supported in the KSAs Open Banking Standard.

Note: A payment request gets created but is not completed till the user authorizes the payment at the bank.

Request Url

POST /paymentInitiation/v1/payments

Request Headers

Header Key Header Value Notes
Authorization Bearer <your_access_token>
Content-Type application/json
X-TG-IdempotencyKey <idempotency_key> Unique request identifier to support idempotency.
Must be less that 40 chars.

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Body

Sample Request

curl --location --request POST 'https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--header 'X-TG-IdempotencyKey: <idempotency_key>' \
--data-raw '{
  "endToEndId": "239846923",
  "paymentAmount": {
    "currency": "BHD",
    "value": "0.016"
  },
  "reference": {
    "label": "Bill Number",
    "value": "655324898230"
  },
  "user":{
    "customerUserId": "7982364",
    "email": "some@email.com",
    "firstName": "John",
    "lastName": "Snow",
    "mobile": "093293845833",
    "userIdentifier": {
      "type": "BH.CPR",
      "value": "332633423"
    }
  }
}'

url = "https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments"

payload = json.dumps({
    "endToEndId": "239846923",
    "paymentAmount": {
        "currency": "BHD",
        "value": "0.016"
    },
    "reference": {
        "label": "Bill Number",
        "value": "655324898230"
    },
    "user": {
        "customerUserId": "7982364",
        "email": "some@email.com",
        "firstName": "John",
        "lastName": "Snow",
        "mobile": "093293845833",
        "userIdentifier": {
            "type": "BH.CPR",
            "value": "332633423"
        }
    }
})
headers = {
    'Authorization': 'Bearer <your_access_token>',
    'Content-Type': 'application/json',
    'X-TG-IdempotencyKey': '<idempotency_key>'
}

response = requests.request("POST", url, headers=headers, data=payload)

OkHttpClient client=new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType=MediaType.parse("application/json");
        RequestBody body=RequestBody.create(mediaType,"{\n    \"endToEndId\": \"99e88j4b\",\n    \"paymentAmount\": {\n        \"currency\": \"BHD\",\n        \"value\": \"0.016\"\n    },\n    \"reference\": {\n        \"label\": \"Bill Number\",\n        \"value\": \"655324898230\"\n    }\n}");
        Request request=new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments")
        .method("POST",body)
        .addHeader("Authorization","Bearer <your_access_token>")
        .addHeader("Content-Type","application/json")
        .addHeader("X-TG-IdempotencyKey","<idempotency_key>")
        .build();
        Response response=client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("X-TG-IdempotencyKey", "<idempotency_key>");
var body = @"{" + "\n" +
@"    ""endToEndId"": ""99e88j4b""," + "\n" +
@"    ""paymentAmount"": {" + "\n" +
@"        ""currency"": ""BHD""," + "\n" +
@"        ""value"": ""0.016""" + "\n" +
@"    }," + "\n" +
@"    ""reference"": {" + "\n" +
@"        ""label"": ""Bill Number""," + "\n" +
@"        ""value"": ""655324898230""" + "\n" +
@"    }," + "\n" +
@"    ""user"": {" + "\n" +
@"        ""customerUserId"": ""7982364""," + "\n" +
@"        ""email"": ""some@email.com""," + "\n" +
@"        ""firstName"": ""John""," + "\n" +
@"        ""lastName"": ""Snow""," + "\n" +
@"        ""mobile"": ""092999999999""," + "\n" +
@"        ""userIdentifier"": {" + "\n" +
@"          ""type"": ""BH.CPR""," + "\n" +
@"          ""value"": ""332633423""" + "\n" +
@"    }" + "\n" +
@"}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Field Type Description
endToEndId string
required		 A unique end to end payment reference that typical reflects in Payee and Payer's statement
6-12 alphanumeric characters with no spaces or special characters
paymentAmount Money
required		 Payment Amount (with currency). This is the amount that is requested to be paid.
Max limit will apply as per configured value for the client
reference object
required		 This is the reference for the payment being made. It could be any identifier that the user may understand or know. Appears on the TG Pay Review payment screen before the payment is initiated.
  label string
required		 The reference field label.
ex: Invoice #, Order Id, Account, etc.
Max length is 20 chars, alphanumeric string with only "-","'" and space is allowed
  value string
required		 The actual reference field.
ex: OST1235, 73643, Mike's Wallet, etc.
Max length is 20 chars, alphanumeric string with only "-","'" and space is allowed
  name string if IBAN is provided, the account holder name of the payee IBAN is required to be sent.
user object, nullable User details.
  customerUserId string, nullable Customer user id.
  email string, nullable Email of the user.
  firstName string, nullable First name of the user.
  lastName string, nullable Last name of the user.
  mobile string, nullable Mobile number of the user.
  userIdentifier object, nullable User unique identifier.
    type string, nullable Type of user national identifier. For example (BH.CPR).
    value string, nullable Value of user national identifier. Will be used by bank to identify the user, if not filled in - user will be asked to enter identification on bank side manually

Note: We only support payment amounts of up to 1000.000 BHD.

Response Fields

Sample Response (200 Success)

{
  "paymentUrl": "https://payments.app.sdb.tarabutgateway.io/banks?lt=eyJraWQiOiI3MDkzRjlFQi1GMDhGLTRENDQtOTg1MS01MEU2NDA2REIzNjUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJyZWRpcmVjdCI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9wYXltZW50L2NhbGxiYWNrIiwiaXNzIjoiaHR0cHM6Ly9hcGkuc2RiLnRhcmFidXRnYXRld2F5LmlvIiwibmFtZSI6IjQ4NmE4YTZjLWE2NjEtNDVkMC1hMmQxLWFjZDk0ODBjYWQ5ZSIsInNraW4iOiJsaW5rIiwiaWQiOiI0OGQxYjM3NC05YTMwLTRjNTUtOWZiOS1lNGFiNDkyMGYwNWUiLCJleHAiOjE2MzI2ODUwODcsImlhdCI6MTYzMjY4NDc4N30.Y-Zem35cHuLMm_Ksntcu5vVeN42EdbM3_dj3gHAtUhD9mBmYuWSPPbUmXd05x4IKd0w9Pw-FwwNQ8s44Wzct5kp5OypAEW51ujKWziMctwE6mdseHacJNm4q_k53MdnBaAzzLtctlHHt7FhWeyanDOIeiv5KUgYvgZy1JGDOI8B8lV4NRT0XqtKV77C7lTfgVwTR6pySk3_JrHK7_8GPTuMkQNQ6poCrgYDar-5Kzm3DJ3QBUZRSH_qNuaTXlQ3xtnpCaJMT4Hm05RO1_MQSXrLQZWJrDZJJMz3z70nSxb0VBKZSHchWY-4EFLec7atwPL7SFH0OVMlwq9Z5W3axfw",
  "paymentId": "65a2c9f4-7a9d-4c66-98da-83babfb88888",
  "endToEndId": "239846923"
}

paymentUrl field must be used to be redirected to TG Pay, which is to authorise and complete the payment flow.

Once the payment is completed TG Pay will make a callback to the default configured redirect url in TG Console

Field Type Description
paymentId string The unique payment Id as generated by Tarabut Gateway for every payment request
paymentUrl string The payment url that needs to be involved to complete the payment authorisation. It embeds all the required payment details in it
endToEndId string The unique end to end Id as provided by the client when initiate the payment

Errors

No endpoint specific errors. Generic errors will carry details around any bad input parameters passed.

Note: This section list out summary of specific errors for this API. Refer here for generic errors and more detailed explanation.

Check Payment Status

This endpoint can be used to check the status of a payment, as well as to receive payment information such as payment amount, payer account, and other references.

Request Url

GET /paymentInitiation/v1/payments/{paymentId}

Request Headers

Bearer token and auth version have to be provided in header of request.

Header Key Header Value Notes
Authorization Bearer <your_access_token>
Content-Type application/json

Note: In addition to the above, also include other headers as documented in Request Headers section

Request Path Parameters

Sample Request

curl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}' \
--header 'Authorization: Bearer <Your_access_token>' \
--header 'Content-Type: application/json'

url = "https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}"

payload = {}
headers = {
    'Authorization': 'Bearer <Your_access_token>',
    'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

OkHttpClient client=new OkHttpClient().newBuilder()
        .build();
        Request request=new Request.Builder()
        .url("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}")
        .method("GET",null)
        .addHeader("Authorization","Bearer <Your_access_token>")
        .addHeader("Content-Type","application/json")
        .build();
        Response response=client.newCall(request).execute();

var client = new RestClient("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <Your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Field Type Description
paymentId string required paymentId of the payment returned as a part of POST /paymentInitiation/v1/payments.

Response Fields

Sample Response (200 SUCCESS)

{
  "paymentId": "a839c12-b00f-42d2-8558-c1a73c05b707",
  "endToEndId": "239846923",
  "paymentAmount": {
    "value": 0.016,
    "currency": "BHD"
  },
  "reference": {
    "label": "Bill Number",
    "value": "655324898230"
  },
  "payerAccount": {
    "providerId": "BLUE",
    "iban": "BH62REDB00200000008527",
    "name": "John Doe"
  },
  "payeeAccount": {
    "providerId": "REDB",
    "iban": "BH62REDBXXXXXXXXXX8528",
    "name": "Hari's Savings"
  },
  "bankTransactionId": "8e12367-7fcc-414a-aebb-a06d86147f55",
  "paymentStatus": "SETTLED",
  "isPayerSaved": false,
  "initiationDateTime": "2021-10-14T01:59:30.208+00:00",
  "lastUpdatedDateTime": "2021-10-14T01:59:30.208+00:00"
}
Field Type Description
paymentId string Unique payment Id as generated by Tarabut Gateway for every payment request.
endToEndId string Unique end to end payment reference id as sent in the request.
bankTransactionId string, nullable Unique transaction id as returned by the payer bank. Some banks show this transaction id as a part of description instead of endtoendId and can be used for reconciliation.
userId string, nullable Unique user id that gets created in TG's system to associate the user context.
paymentAmount Money Payment Amount (with currency). Amount that was requested to be paid.
reference string, nullable This is the reference for the payment being made as sent in the request.
  value string The reference field value.
  label string The reference field label.
payerAccount string, nullable Payer account details (debtor account) used for initiating the payment.
  providerId string Bank identifier of the payer account.
  payerAccountId string Unique payer account identifier. If payer saved is true, this can be stored and used to send back in the subsequent request to ease subsequent payment experience.
  maskAcctNumber string Masked account number or iban that can be used to display it to the users for payment confirmation or show it for returning user journey to have then select the saved payer account.
  iban string, nullable The IBAN number of the payer account. It can be used to initiate refund process. This is not returned unless enabled for.
payeeAccount string Payee account details (creditor account) where the payment was made.
  providerId string Bank identifier of the payee account.
  payeeAccountId string Unique payee account identifier.
  maskAcctNumber string Masked account number or iban of the payee account.
  iban string, nullable The IBAN number of the payer account. This is not returned unless enabled for.
paymentStatus string The status of the payment initiated.
enum: Payment Status
isPayerSaved boolean If the user chooses to save the payer account, this flag will be set to true. It can
initiationDateTime string Timestamp when the payment request was initiated with TG in DateTime format
lastUpdatedDateTime string Timestamp when the payment was last updated in DateTime format. Typically it gets updated with status upon payment completion.

Payment Status

paymentStatus Description
PENDING Client has initiated the payment. This is the state that gets returned till the payment request is accepted by the payer bank for processing. This is the default state when a POST /paymentInitiation/v1/payments api call is made.
DECLINED User has declined the payment consent with TG. This is a terminal status.
REJECTED User has rejected, refused or cancelled the payment at the bank during authorization.
IN_PROGRESS Payment is authorized and is in processing.
DEBIT_COMPLETE Payer Bank is debited. In real time payments, this is a very intermittent state.
SETTLED Payee Bank is credited and payment is complete.
FAILED A technical error has occurred and payment could not be processed.

Errors

No endpoint specific errors. Generic errors will carry details around any bad input parameters passed.

Note: This section list out summary of specific errors for this API. Refer here for generic errors and more detailed explanation.

Error Handling & Schema

A detailed list of all the errors thrown by TG APIs. Please refer Error Response in the overview section to understand generic error schema.

Generic Errors

Http Status Code: 400

{
  "error":"INVALID_FIELDS",
  "errorMessage":"Required fields missing or invalid field or field values sent in the request",
  "details":[
    {
      "fieldName":"paymentAmount.value",
      "message":"must not be null"
    }
  ],
  "traceId":"233333"
}

These are common errors that can be thrown for any API endpoint.

HTTP Code error Description
500 INTERNAL_SERVER_ERROR Returned when an unexpected error as occurred on TG's end.
503 PLANNED_MAINTENANCE Returned when the services are unavailable due to a planned maintenance. If you are not informed prior about the maintenance, please reach out to TG support team.
403 API_ACCESS_DENIED Access Token used for this API call is not issued with required scope for this API call. Please check your scope configured or requested for the access token.
401 UNAUTHORIZED_ACCESS Access token used is invalid or expired. Regenerate the access token.
400 INVALID_REQUEST Body could not be parsed or invalid content type passed mis-matched. Review your request body & header.
400 INVALID_FIELDS Required fields missing or invalid field or field values sent in the request; This error will also return details object providing details around specific field. Review the input request parameters.
400 INVALID_HEADERS Required header field is missing or invalid in the request; This error will also return details object providing details around specific header field. Review the header parameters
404 API_NOT_FOUND End point does not exist. Re-verify your end point or API url and path parameters.

Note: API Specific errors are documented along with respective end points above.

Changelog

What's new with TG!

The changelog provides a view of any changes or updates made to the TG APIs and associated products. Keep a track of any enhancements or bug fixes with our regular updates.

Release Account Information APIs

Account Information Account Information product is launched in Bahrain which enables users and businesses to request for account and categorised transaction information from financial institutions upon end-user consent securely.

March 2022

Release Payment Initiation APIs

Payment Initiation Payment Initiation product is launched in Bahrain which allows for seamless bank to bank payments for various use cases such as bill payment, checkout, and account to account payments.

October 2021

cURL java-OkHttp python-Request C#-RestSharp