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?
- Provides an optimized user experience to review and authorize payments.
- It instantly connects you to our growing network of banks that support payment initiation.
- Designed to work seamlessly on desktop and mobile devices like iOS and Android.
- Maintains compliance with changing open banking standards.
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?
- Provides an optimised user experience to review permissions and consent for data access.
- It instantly connects you to our growing network of banks across region that support account information.
- Designed to work seamlessly on desktop and mobile devices like iOS and Android.
- It is secure and maintains compliance with changing open banking standards.
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 -
- Sandbox environment where you try and test your integration without requiring live bank accounts and
- 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:
- All the data in the sandbox environment is completely segregated from production. You cannot migrate a user or any data from sandbox to production.
- The API keys (clientId and clientSecret) will be different for sandbox and for production.
- All testing should be done in the sandbox environment. Any activity in production will be billed.
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. |
Link Schema
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:
- Adding new API endpoints
- Adding new optional request parameters to existing API endpoints
- Adding new data elements/properties to existing API response schemas
- Changing the order of elements in the existing API responses.
- Changing the length or format of opaque strings or data elements, such as reference ids, API identifiers, error messages, and other human-readable strings.
- Adding new enum values for error is treated as backward compatible changes.
- Adding new event types. - webhook listener should gracefully handle unfamiliar event types.
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
- Sign up for a developer account at TG Console
- Create your Client ID and Secret for sandbox in order to access our API services.
- Generate Access Token and Initiate Payment by providing payment amount and an endToEndId.
- 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
- Sign up for a developer account at TG Console
- Create your Client Id and Secret for sandbox in order to access our API services.
- 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. - Invoke the returned TG Connect URL on your client app for the user to consent for account access.
- 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:
- Call POST /auth/v1/token from your server using your API keys to generate an access token.
- 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.
- 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.
- 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:
- Call POST /auth/v1/token from your server using your API keys to generate access token.
- 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.
- 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
- Sandbox environment and test accounts is not for real bank simulation and is purely intended for integration testing in Sandbox!
- Blue Bank is hosted by Tarabut Gateway and is not a real bank. This may not reflect real bank behavior.
- Blue Bank enables simulation of a basic authentication flow and returns close to real user's data that cannot be used for variations of actual banks & accounts.
- It is highly recommended to use real accounts for user acceptance testing in production before opening up the service for all users.
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 -
Download and install the Postman app
Download and import the TG API Endpoints postman collection. Copy this JSON link and import into Postman
Configure the environment with your API keys by adding them as Postman collection variables.
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:
Select the Tarabut Gateway API Collection
Click the Variables tab
Copy your API keys from TG Console. Update the ClientId and ClientSecret.
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
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. |
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 |
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