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 here. You will be provided with access to Developer Console where you can create and manage the API keys and App settings required for the service.

If you have any questions, please email us at developers@tarabutgateway.com

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

API Access & Environments

Start by creating an account on Tarabut Gateway Developer Console. Upon completion of the signup process you will then access the API keys along with API URL for Sandbox by clicking on "Create API Keys" from the dashboard and confirming the region. This creates an App - in other terms a project. You can come back and edit/manage the app settings any time from the console.

These API keys can be used to obtain OAuth2 access token using token endpoint. The access token must be supplied as a Bearer token within every service API call made to TG platform.

Environments Overview

TG has two environments -

  1. Sandbox environment where you try and test your integration without requiring live bank accounts and
  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.

You can find the API URLs for these environments from console.

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.

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.

Versioning

The API base URL contains a version identifier. The current version is v1. Tarabut Gateway will support one prior version for a maximum of six months after the introduction of a new version.

A detailed changelog will be updated from time to time detailing the changes introduced be it either backward incompatible or compatible changes.

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:

Get Started in Sandbox

Use our APIs to make a single immediate payment or access account information in just a few steps. Here is how it works-

Getting Started with Payment Initiation

  1. Sign up for a developer account at TG Console
  2. Create your Client ID and Secret for sandbox in order to access our API services.
  3. Generate Access Token and Initiate Payment by providing payment amount and an endToEndId.
  4. We will provide you with Payment URL to TG Pay which is a simple interface to select bank, review payment and authorise payment at the bank.

You can quickly get started by using our Postman collection.

Getting Started with Account Information

  1. Sign up for a developer account at TG Console
  2. Create your Client Id and Secret for sandbox in order to access our API services.
  3. Generate Access Token and Create Intent by providing User details.
    This will return a URL to TG Connect which is a simple interface for the user to select bank, review permissions and authenticate with the bank and selecting accounts.
    Sandbox will always redirect to a test bank called Blue bank.
  4. Invoke the returned TG Connect URL on your client app for the user to consent for account access.
  5. Fetch account balances and transactions from your server application.

You can quickly get started by using our Postman collection.

Getting your API Keys - Setup

In order to use TG APIs, it is necessary to generate an access token using API keys (clientId and clientSecret). You can get the API keys by signing up at TG Console. This is a one time setup. As we generate the API keys, we also create your first app to get you started quickly!

After successfully setting up an application through TG Console, you can access the Keys and URL from API Keys menu item.

Generate Token & Make a Payment

You will use both a server and a client-side component to access the TG APIs. A typical payment flow looks like this:

  1. Call POST /auth/v1/token from your server using your API keys to generate an access token.
  2. Call POST /paymentInitiation/v1/payments to initiate a payment which will return a unique TG Pay payment URL for your user to authorize the payment from your client app.
  3. Upon successful payment authorization, the payment will be initiated and a unique paymentId will be returned along with paymentStatus. Use Test Account for your sandbox testing.
  4. Store this paymentId along with other details for your future reference or accessing the payment status details using GET /paymentInitiation/v1/payments from your server.

Generate Token & Access Data

You will use both server and a client-side component to access the TG APIs. A typical account information flow to access data looks like this:

  1. Call POST /auth/v1/token from your server using your API keys to generate access token.
  2. Call POST /accountInformation/v1/intent to initiate account linking which will return a unique TG Connect URL for your user to consent and authenticate with bank for data access from your client app.
  3. Upon successfully connecting a bank, You can now access the accounts, transactions using GET /accountInformation/v1/accounts and GET /accountInformation/v1/accounts/{accountId}/transactions respectively from your server.

Sandbox Testing

Tarabut Gateway has created a mock/dummy bank by name "Blue Bank" to help developers integrate and test the integration.

This is a minimalistic simulated bank experience whereupon initiating the payment URL and selection of Blue Bank, takes you to the Blue Bank website to authenticate and authorize the payment.

Please use any four-digit number to authenticate to Blue bank.

Simulating Different Redirection flows

App to App Redirection

Coming Soon

We are actively working to enhance our Blue Bank application to be available as an App so that you can test this flow.

App to Web or Web to Web Redirection

To test the web redirection flow which most banks support, once you select Blue Bank the widget will automatically redirect to Blue Bank web authentication page.

Decoupled Authentication

Sorry, this is not supported today through our current Blue Bank.

Don't worry! TG Pay or the TG Connect widget will handle this and there is no integration work that will be required at your end.

Learn more about different authentication flow here.

Considerations

Developer Tools

Postman Collection

Postman is a convenient tool for a quick and easy way to try out TG APIs without writing any code. We have created the Postman collection which has pre-formatted requests of TG API endpoints. It consists of all endpoints that are required to complete an account information or payment initiation flow. All you have to do is -

  1. Download and install the Postman app

  2. Download and import the TG API Endpoints postman collection. Copy this JSON link and import into Postman

  3. Configure the environment with your API keys by adding them as Postman collection variables.

  4. Start using each API as explained in the Get Started guide

Note: You will need to open the payment URL in a browser, as returned by the POST /paymentInitiation/v1/payment endpoint, to complete the payment flow. Similarly, you will need to open the connect URL in a browser, as returned by POST /accountInformation/v1/intent endpoint, to initiate the bank connection flow.

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 TG Console. Update the ClientId and ClientSecret.

  4. Save your changes and start making API requests!

Further information on managing Postman environments can be found here.

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.

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

Generate Access Token

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

Works with - Coming Soon

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.

Provider APIs

Fetch supported providers along with details. Each Provider entity represents a financial institution with a distinct login URL.

Note: It is possible that a financial institution might have multiple logins for different services (or different lines of business). These will be represented as different providers.

Description Endpoint
Fetch Providers GET /v1/providers

Provider's Coverage

TG supports almost all the banking institutions in Bahrain today. We are actively working to expand our coverage and integrations for UAE and Saudi Arabia.

Get Providers

Get a list of all the financial institutions TG can connect to for PISP-related services. The details about the financial institutions can be used to build an account selection experience.

Coming soon: - The result will be filtered based on the products and regions that are enabled for the client and the App. - The result will include providers for AISP-related services.

Required authentication token scopes

Coming soon

Request Path

GET /v1/providers

Request Headers

No endpoint-specific headers

For the list of headers required in general by TG APIs, click here.

Sample Request

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

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

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/v1/providers")
  .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/v1/providers");
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);

Response Fields

Sample Response (200 Success)

[
  {
    "providerId": "NBOB",
    "name": "National Bank of Bahrain",
    "displayName": "National Bank of Bahrain",
    "logoUrl": "https://tg-external-entities.s3.me-south-1.amazonaws.com/NBOB.png",
    "countryCode": "BHR",
    "status": "ACTIVE"
  }
]

List of all the financial institutions TG can connect to for PISP-related services.

Field Type Description
providerId string Unique TG identifier for the provider.
name string The provider or financial institution's official name.
displayName string Shorter version of the provider name.
status string The status of the provider.
Enum : Provider Status
logoUrl string The static logo URL of the institution.
Disclaimer: This is the logo of the bank as available in the public domain for use in the bank selection screen if required.
countryCode string Country code of the provider in ISO 3166-1 alpha-3.

Note: In Sandbox, Bank will be the only supported provider returned.

Provider Status

Status Description
ACTIVE The provider is integrated with TG. A provider with this status can, for example, be listed for the end-user to select in the bank selection experience.
INACTIVE The provider is not available.
IN_DEVELOPMENT TG is actively integrating with the provider and it is expected to be ACTIVE soon. This status can be used, for example, to label a provider as Coming Soon in the bank selection experience.

Errors

No endpoint specific error.

Note: This section lists a summary of specific errors for this API. For a detailed list of general-purpose errors returned by TG APIs, click here.

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

POST /paymentInitiation/v1/payments 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, it returns a TG Pay PaymentURL along with a paymentId for the user to authorize the payment requested

TG Pay API automatically chooses the best and most appropriate payment rail to make the fastest payment with no or lowest fees to the user. Note: A payment request gets created but is not completed till the user authorizes the payment at the bank..

Works with - Coming Soon

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
payeeAccount object This is the optional Payee account information that can be passed to dynamically set the payee account information
    payeeAccountId string For certain use cases, multiple payee accounts can be pre-configured. Passing the payee account id will allow to make the payment to this payee account instead of default.
Alternatively, if the client is using account information service and want to allow payments within linked bank accounts, or in me2me payment use case where account needs to be verified first, we can pass the accountId here to which the payment needs to be made.
    iban string IBAN of the Payee account
To be used only for Peer 2 peer payments or payout use case (needs explicit approval and enablement) where payee creation is required at a user level.
    name string if iban is provided, the account holder name of the payee iban is required to be sent.
payerAccount object This is the optional Payer account information that should be passed to preselect the payer's bank account. Typically gets used in the subsequent payment flow.
    providerId string Providing providerID will skip the bank selection screen in TG Pay and directly take the user to review payment screen. This is typically used when client wants to implement bank selection at their end instead of one present in TG Pay. It also needs to be sent in the request when iban is passed as payerAccount field.
    payerAccountId string In case of subsequent payment, clients are required to pass this payerAccountId as returned in response to initial payment. This simplifies the return user journey by skipping bank and account selection during payment authorisation/consent flow.
    iban string IBAN of the Payer account
If the client already has IBAN of the account from which the payment needs to be made, they can pass this it here. This pre-selects the bank account during authorisation/consent flow.
    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.

Works with - Coming Soon

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.

Account Information

Connect Bank accounts using TG Connect and gain access to account and transaction information.

Supported APIs are given below

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

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.

Works with - Coming Soon

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 Available Providers)
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://accounts.app.sdb.tarabutgateway.io/confirm?lt=token",
  "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.

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.

Get Intent

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

Request Url

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, COMPLETED, CONSENT_INITIATED, CONSENT_REJECTED, UNKNOWN.

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

Works with - Coming Soon

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",
      "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.
  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).

Works with - Coming Soon

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

Works with - Coming Soon

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}/transactions

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/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), 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.
  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.

Category Group

Group Definition
Income Payments made into account from other financial entities relating to employment, investments, support from the state, or any other income source.
Expense Payments made from account towards goods and services.
Other Other transactions that do not fall into income or expense groups
Uncategorised Transactions that our service is not able to assign a category to

Category Name

Group Name Definition
Income Salary & Wages Payment from an employer
Interest Account interest accumulation
Profit Profit paid by the bank for customer deposits
Benefits Financial help payment from government, or charitable organisations
Retirement & Pensions Payment towards retirement from government or private institution
Reimbursements & Refunds Reimbursements relating to merchants, tax, insurance claims
Deposits Money deposits; e.g. ATM, cheque, online
Investment Income Earnings from investment vehicles; e.g. cryptocurrency exchanges, stock-trading applications
Other Income All other payments that represent income
Expense Transport Payment towards transportation or travel. Includes automotive expenses.
Entertainment & Leisure Payment towards entertainment purposes; e.g. events, online content, entertainment venues, games, tourism
Personal Care & Wellbeing Payment towards personal care; e.g. cosmetics, wellness or fitness providers; e.g. gym
Healthcare & Medical Payment towards healthcare and medical providers
Education Payment towards educational institution or material
Childcare Payment towards childcare; e.g. nurseries, schooling
Pets Payment towards pet supplies and care
Charity & Donations Payment towards charity purposes
Construction & Trades Payment towards construction, home improvements, building materials, and tradesmen
Currency Exchange & Remittance Payment towards money service providers; e.g. currency exchange, international remittance
Rent Payment towards rental of home or commercial properties
Hotels & Lodging Payment towards short-term accommodation
Business & Personal Services Payment towards professional service providers with specialised skills, tools or licenses; e.g. legal, accounting, tailors, laundry, logistics
Insurance Payment towards insurance provider; e.g. health, life insurance
Groceries Payment towards merchant selling foodstuff and perishable household supplies; e.g. supermarket, convenience store
Shopping Payment towards general merchandise, electronics, fashion, e-commerce
Fees & Charges Payment towards financial institution or government; e.g. late bank payment charges, overdraft, municipality fees
Bills & Utilities Payment towards essential services; e.g. phone, broadband, water, energy
Loans & Mortgages Payment towards loan or mortgage repayment
Eating Out Payment towards dining; includes restaurants, venues that serve food & drink
Taxes Tax payment
Cash Withdrawals Cash withdrawals from ATMs or CDMs
Islamic Financing Payment towards Shari'a-compliant financing contracts; e.g. Murabaha
Other Expenses Expense not aligned to other existing category
Other Transfers Money transfers from/to other bank accounts
Credit Card Payments Payment towards credit card repayment
Investment Payments Payment towards investment vehicles; e.g. cryptocurrency exchanges, stock-trading applications
Savings Money transfer to savings account
Other Transactions Other transactions not aligned to other existing category
Uncategorised Uncategorised Transactions which we have not been able to categorise

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.

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.

Works with - Coming Soon

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.

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.

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

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

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' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {valid-tg-token}' 

import requests
import json

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

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

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.

Enterprise Services

Tarabut Gateway offers premium features, endpoints and capabilities, some of which are listed below that enable deeper custom integrations. Get in touch to partner with us to power your products and services.

Webhooks

We allow subscription to multiple URLs to drive a specific web hook event. Once subscribed, your URL will begin recieving events (e.g. new transactions available, balance changes and consents expired) to drive more real time experiences in your product or service.

SDKs

As an alternative to REST based APIs, TG also provides SDK to make it faster to build integrations with TG's products. It also removes the hassle of maintaining those connections yourself and is constantly updated to give end users the best possible user experience.

PFM Feature Functionality

Tarabut Gateway has deep experience of building PFMs for banks and fintechs. We can provide customers more value with our ready to use solutions – and help end users better understand their needs – with tools and personalised insights that help improve their finances. Our PFM end points enable rapid build and delivery of PFM use cases - to increase engagement, inspire action and boost conversion.

*To learn more about our Enterprise features and how we can partner with you to power your use case please contact us on developers@tarabutgateway.com. *

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