Introduction
Welcome to Tarabut Gateway (TG) API platform documentation. Here you will find everything you need to build features, apps, and experiences using TG API services.
All our endpoints follow standard RESTful principles. You will find all the example request and response payload snippets along with detailed parameters and field descriptions to get you up and running quickly.
For you to start interacting with our APIs, please sign up for access to the right developer portal based on your country of operation.
Country | Developer Portal URL |
---|---|
Bahrain | https://portal.tarabutgateway.io/sign-up |
Saudi Arabia | https://portal.sau.tarabutgateway.io/sign-up |
You will be provided with access to Developer Portal where you can create and manage the API keys and App settings required for the service.
If you have any questions, please navigate to our Enquiry page.
Environment URLs
TG has two environments -
- Sandbox environment where you try and test your integration without requiring live bank accounts.
- Production environment where you will take the integration live for real users. This environment is fully scalable and designed to work with live banks.
Country | Domain Url |
---|---|
Bahrain | Sandbox : https://api.sandbox.tarabutgateway.io Production : https://api.tarabutgateway.io |
Saudi Arabia | Sandbox : https://api.sau.sandbox.tarabutgateway.io Production : https://api.sau.tarabutgateway.io |
A few points to know:
- 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.
Getting Started Guide
This overview of how to incorporate Tarabut Gateway products/services into your product (known as an integration) outlines the broad requirements for using the Tarabut Gateway platform and connects you to resources for choosing and implementing the best Open Banking solutions for your platform.
1. Create a free developer account
A TG developer account enables you to develop and test your app in an environment that’s isolated from production. API calls sent from this environment are not actual transactions and are simulated to closely match the production API calls and user journeys.
Developer Portal Urls by country :-
Country | Developer Portal URL |
---|---|
Bahrain | https://portal.tarabutgateway.io/sign-up |
Saudi Arabia | https://portal.sau.tarabutgateway.io/sign-up |
Depending on the TG APIs you plan to work with, you may need to take additional steps to gain access to your desired functionality.
To start testing our APIs in sandbox and to gain access to abundant bank dummy data, create your developer account today!
2. Generate Sandbox Credentials
Next, you generate your sandbox credentials in your developer account. On the TG platform, sandbox credentials are a set of API client_id and client_secret.
You can create an app by following the below steps :-
- Once a user has signed up and created an account on the developer portal the user will be redirected to the landing page of the developer portal.
- On the developer portal landing page the user has to click on the Generate Sandbox Credentials button.
- The user will then be navigated to the App Settings page where the user will then be able to see the generated client_id and client_secret.
3. Configure app settings
After you generate your sandbox credentials, you may then proceed further to configure your
- Display Name : The display name is captured on the app settings page of the developer portal. This information is usually the company's name that needs to be rendered on the UI during the user journey.
Note: If you do not provide a display name, then by default the display name will be taken as the company name.
- Redirect URI : The redirect URI (URL) is the URI provided by the user to which TG will redirect the browser after completion of a payment transaction or bank connect journey.
Note: You can set multiple redirect URIs to your integration on the developer portal.
4. Generate your Access Token
Once you've generated your sandbox credentials and have configured your app settings in your developer portal account, you’re ready to continue developing/integrating.
In order to make a successful sandbox API call, you need to first generate an Access Token.
These sandbox credentials can be used to obtain OAuth2 access token. The access token must be supplied as a Bearer token under headers within every service API call made to TG platform.
Authentication API
Obtain access token which is required for accessing services
| Country | Domain Url |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Bahrain | Sandbox : https://api.sandbox.tarabutgateway.io
Production
** : https://api.tarabutgateway.io |
|Saudi Arabia*
| **Sandbox* : https://api.sau.sandbox.tarabutgateway.io
*Production
* : https://api.sau.tarabutgateway.io |
Endpoint : /auth/v1/token Method : POST
Request Body Parameters | Description |
---|---|
clientId | Pass the sandbox client_id generated on the developer portal. |
clientSecret | Pass the sandbox client_secret generated on the developer portal. |
grantType | Pass a static value client_credentials to this parameter. |
redirect_uri | Pass the redirect_uri that you configured on the developer portal under the app settings page. |
Note: The Access Token expires after 300 sec.
Sample Request
{
"clientId": "4039c150-335b-4b8b-ab66-eca6953xxxxx",
"clientSecret": "rpSFlA6xeuSzI7ZJVIgW3Yyskakxxxxx",
"grantType": "client_credentials",
"redirect_uri": "http://localhost:3000/landingpage"
}
Sample Response
{
"accessToken": "eyJraWQiOiI5N2UzZTQ0NS0wZWU1LTRiNmItODVmOC1hNmY4YTMzMjYzZTIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0ZW5hbnRfaWQiOiJ0YXJhYnV0X2dhdGV3YXkiLCJhdWQiOiJodHRwczovL2FwaS5zYXUuc2FuZGJveC50YXJhYnV0Z2F0ZXdheS5pbyIsImlzcyI6Imh0dHBzOi8vYXBpLnRhcmFidXRnYXRld2F5LmlvL2F1dGgiLCJjbGllbnRfY291bnRyeSI6IlNBVSIsInRnX2NsYWltcyI6WyJwYXllZTp3cml0ZSIsInBheW1lbnQ6d3JpdGUiLCJwYXllcjp3cml0ZSIsInN0YXR1czpyZWFkIl0sImN1c3RvbWVyX3VzZXJfaWQiOiI2Njc4IiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly93d3cuZ29vZ2xlLmNvbSIsImV4cCI6MTY4NjczOTM3MCwiaWF0IjoxNjg2NzM5MDcwLCJjbGllbnRfbmFtZSI6IlRHICIsImNsaWVudF9pZCI6IjQwMzljMTUwLTMzNWItNGI4Yi1hYjY2LWVjYTY5NTM2ZDBiOSJ9.C7YVROTTVSXFXTSb5fkeEZKiMqJDJehxGmloi4VIiB9TxuIuxfVrlrLzUTDAOjryydBHKJb8AOpLJGBBCFIPBJY7Dw-WMnLn6lSjGMQkBiTKbktDSJ1_QLME7aTK8rvRwgSLXtGVzGDo3i1TK-9nD8EUvV022h8w3mmABIH_KCxFwensLYfDw_-iTCuHqQz1XXQT3Y8ZcHxTmaG8zKW3gs3m11b_b59q4zRBdTWKW60nVbduFfR8unrFy-CPqtVo3S96_DYfTnGeTrcm_XJ4p9guHTOK0RXEl86GiVp4Yc9meMz47uWOHAYoIPBCbJEsMmxxxxxxxxxxxxxxxxxxxx",
"expiresIn": 300,
"tokenType": "Bearer"
}
5. Go-Live
After you have completed your integration and are ready to go-live, you need to follow the following steps to request for production access :-
i. Login to DevPortal :-
Login to your dev portal account and navigate to the app settings page.
ii. Click on LIVE mode :-
Once you're on the app settings page you need to click on the *LIVE mode toggle.
iii. Request for production access :-
Once you click the LIVE mode toggle, you have to click on the "Request for production credentials" button.
iv. Complete KYB :-
Once you have requested for production access, we will create a support ticket and you'll receive an email in your registered email address which will ask you to complete the KYB with TG.
v. Make 1st production API call :-
Once the KYB is completed, you'll get a notification regarding KYB completion and you'll be able to see the API production credentials on the developer portal. You can then make your 1st production API call and go-to-market!
API Protocols
The service is made available through Application Programming Interface (API) endpoints, all of which adhere to REST design principles. Standard HTTP verbs and status codes are used for requests and response statuses. Request and response payloads are of JSON format.
To ensure data security and privacy, TG API is served over HTTPS TLS v1.2+ protocol only.
Request Headers
The following header attributes are required to be sent for almost all API calls and the body must have a valid JSON. API specific headers are documented along with respective APIs.
Sample Header Attributes
Content-Type: application/json
Authorization: Bearer <your_access_token>
X-TG-IdempotencyKey: <unique_idempotency_key>
X-TG-UserLoginTime: <your_user_last_loggedin_time>
X-TG-UserIPAddress: <your_user_IP_address)
X-TG-DeviceUserAgent: <your_user_device_UserAgent)
Header Key | Value | Description |
---|---|---|
Content-Type | application/json |
Represents the format of the payload being provided in the request. This must be set to application/json, except for the endpoints that support Content-Type other than application/json |
Authorization | Bearer <your_access_token> |
Credentials (Generated from /token end point) to be provided to the Authorisation or Resource Server in Bearer Authentication Scheme. Required except for /token endpoint. |
X-TG-IdempotencyKey | <Unique_Key> |
Unique request identifier to support idempotency for POST Methods. Must be less that 40 chars. |
X-TG-UserIPAddress | <User_IP_Address> |
User's/PSU's IP address if they are currently logged in with your application. |
X-TG-DeviceUserAgent | <User-Agent_from user's_device> |
Indicates the user-agent from the device or the browser that the Customer/PSU is using. |
X-TG-UserLoginTime | <Your_User's login Time |
The time when the user/PSU last logged in with your application in ISO-8601 format (YYYY-MM-DDTHH:mm:ssZ) ex: 2021-10-13T13:01:15Z |
Note: The X-TG-UserIPAddress header identifies whether or not the user is present, which the provider may utilize to authorize data updates/API queries if the user is present.
The passing of the User IP address and Device User-Agent header value to TG may be subject to Data Privacy regulations and concerns.
Success Response
The successful responses will have status codes 200 or 201 and have relevant response content where required.
However, 204 No Content
and 205 Reset Content
status codes won't contain response content.
All our responses will be in JSON format with UTF-8 encoding.
Error Response
We use standard HTTP response codes for success and failure notifications. In general, 40X codes are for developer or user-related failures, and 50X codes are for TG related issues.
You can read about each error codes, description and sample response here.
Sample Error Response
Http Status Code: 400
{
"error": "INVALID_FIELDS",
"errorMessage": "Required fields missing or invalid field or field values sent in the request",
"details":[
{
"fieldName": "paymentAmount.value",
"message": "must not be null"
}
],
"traceId": "233333"
}
Field | Type | Description |
---|---|---|
error | string | Unique short error code, enough to understand the error as well as use it in code. New error codes may be added as we introduce new features and enhance functionalities. |
errorMessage | string | Descriptive error message that helps debugging and understand the cause for failure. This can change over time and is not safe to use in code. |
details | Object[] nullable |
An array of error details providing more details around error (like field specific level). |
fieldName | string nullable |
The actual field name which failed validation or for which the error was thrown. |
message | string nullable |
Descriptive error message specifying the reason for failure for the field. |
traceId | string | Unique trace Id that must be shared with TG support team to help debug when you face any issue. |
Data Types
Data Type | Standard |
---|---|
string encoding | UTF-8 |
dateTime | ISO-8601 (YYYY-MM-DDTHH:mm:ssZ) |
date | ISO-8601 (YYYY-MM-DD) |
currency code | ISO-4217 (BHD) |
country code | ISO 3166-1 alpha-3 (BHR) |
number (float) | Up to 3 decimals |
Money Schema
We use a money object for all amounts or balances (both request and response) which includes an amount value along with a currency code
Sample Money Response
{
"value": 100.123,
"currency": "BHD"
}
Field | Type | Description |
---|---|---|
value | number | The actual amount value Amounts are always returned up to 3 decimal places depending on the currency. |
currency | string | Currency code associated with amount. Supports all ISO 4217 currency codes. |
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. |
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 |
Versioning
The API base URL contains a version identifier. Each endpoint will refer to the latest version in the document.
Backward Compatibility
Tarabut Gateway aims to make integration as seamless as possible for its client and takes all possible steps to prevent backward-compatibility breaks. In the scenario where a change is unavoidable, we either create a new endpoint by renaming the url or updating the version.
Tarabut Gateway considers the following changes to be backwards-compatible or non-breaking changes:
- 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.
Using Postman to access TG's APIs
Being able to try out an API as quickly as possible is instrumental when learning about the API's features. One of the tools to help you get up and running quickly is Postman, which allows you to organize and run groups of REST API calls. We have added a Postman collection for both Bahrain and Saudi Arabia users who will be able to access these APIs and mak
Step 1: Install Postman
Before you can use Postman, you need to install it. Visit https://www.getpostman.com/ and download the preferred version for your system.
Step 2: Get the Postman collection
This step is easy. Just click on the Run in Postman button on this page and you’ll be prompted to import the collection inside of Postman.
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 Dev Portal. Update the ClientId and ClientSecret.
Save your changes and start making API requests!
Further information on managing Postman environments can be found here.
Step 3: Try out the APIs!
Now it’s time to try out some API calls in Postman!
Our collection has a few folders in it, each with different API calls to fulfill a different task, along with a Bahrain & KSA reference that contains all of the endpoints. Let’s look at the First Transaction folder. It has all of the calls for a standard e-commerce scenario of creating a customer, charging them, and viewing their resulting transaction. You should be able to run each request in order without any trouble. Relevant IDs in the responses will be automatically added to your environment for subsequent requests. You’ll need to use your API Sandbox credentials to use the testing card nonces.
Tips and Tricks: Code Snippets
The Postman app has the ability to instantly generate code snippets in numerous languages and frameworks, so you can make the same request from your application.
Once you’ve selected an API call, click "Code" on the right, and select your language from the drop-down list.
Authentication APIs
TG uses access tokens to authenticate and authorize API requests. The access token is provided in the HTTP Authorization header as Authorization: Bearer
Generate Access Token
Environment | Domain Url |
---|---|
Sandbox | https://oauth.tarabutgateway.io/sandbox/ |
Production | https://oauth.tarabutgateway.io/ |
Authentication API endpoint
Description | Endpoint |
---|---|
Fetch access token | POST /token |
Request Header
Header Key | Header Value | Notes |
---|---|---|
Content-Type | application/json | |
X-TG-CustomerUserId | <Your unique user identifier value> |
This value is used to identify your user in our system. Necessary for establishing the user context of the payment being processed or the account information being retrieved. Not required for guest payment checkout. Must be less than 40 chars. |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Body
Sample Request
curl --location --request POST 'https://oauth.tarabutgateway.io/sandbox/token' \
--header 'Content-Type: application/json' \
--header 'X-TG-CustomerUserId: <customer_user_id>' \
--data-raw '{
"clientId": "<your client id>",
"clientSecret": "<your client secret>",
"grantType": "client_credentials"
}'
Authentication API endpoint (Old version)
Note: This version of the API will be deprecated soon. Clients should integrate the new version of the API.
Description | Endpoint |
---|---|
Fetch access token | POST /auth/v1/token |
Fetch access token for your authentication and use to access TG APIs
HTTP Request Url
POST /auth/v1/token
Request Header
Header Key | Header Value | Notes |
---|---|---|
Content-Type | application/json | |
X-TG-CustomerUserId | <Your unique user identifier value> |
This value is used to identify your user in our system. Necessary for establishing the user context of the payment being processed or the account information being retrieved. Not required for guest payment checkout. Must be less than 40 chars. |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Body
Sample Request
curl --location --request POST 'https://api.sandbox.tarabutgateway.io/auth/v1/token' \
--header 'Content-Type: application/json' \
--header 'X-TG-CustomerUserId: <customer_user_id>' \
--data-raw '{
"clientId": "<your client id>",
"clientSecret": "<your client secret>",
"grantType": "client_credentials"
}'
url = "https://api.sandbox.tarabutgateway.io/auth/v1/token"
payload = json.dumps({
"clientId": "<your client id>",
"clientSecret": "<your client secret>",
"grantType": "client_credentials"
})
headers = {
'Content-Type': 'application/json',
'X-TG-CustomerUserId': '<customer_user_id>'
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\"clientId\": \"<your client id>\",\n\"clientSecret\": \"<your client secret>\",\n\"grantType\": \"client_credentials\"\n}");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/auth/v1/token")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("X-TG-CustomerUserId", "<customer_user_id>")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/auth/v1/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("X-TG-CustomerUserId", "<customer_user_id>");
var body = @"{" + "\n" +
@"""clientId"": ""<your client id>""," + "\n" +
@"""clientSecret"": ""<your client secret>""," + "\n" +
@"""grantType"": ""client_credentials""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Field | Type | Description |
---|---|---|
clientId | string required |
Your application Client ID. You can get this from TG Console |
clientSecret | string required |
Your application Client Secret. You can get this from TG Console |
grantType | string required |
"client_credentials" - static value |
scopes | string | Send on the scope in case you want to limit access token use for better security. Multiple scopes can be passed separated by space |
redirect_uri | string | Provide a redirect url here if multiple URLs are configured in the TG console. |
Response Fields
Sample Response (200 Success)
{
"accessToken": "Your_access_token",
"expiresIn": 3600,
"tokenType": "Bearer"
}
Returns the accessToken that needs to be used for TG API authentication.
Field | Type | Description |
---|---|---|
accessToken | string | Generated access token that needs to be used for API access in Authorization header |
expiresIn | integer | Validity of Token in seconds |
tokenType | string | "Bearer" |
Errors
HTTP Code | Error | Description |
---|---|---|
403 | INVALID_SCOPES | Requested product scope is not available or subscribed for this client id |
400 | INVALID_API_KEYS | Invalid or missing client id or secret provided |
403 | API_ACCESS_DENIED | Client ID suspended/blocked |
Note: This section list out summary of specific errors for this API. Refer here for generic errors and more detailed explanation.
Providers
List of financial institutions we provide coverage to across our product offerings. It includes below API :
Description | Endpoint |
---|---|
Get Providers | GET /v1/providers |
Available Financial Institutions
Below API enables you to retrieve list of bank institutions supported by TG.
Request Url
GET /v1/providers
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Sample Request
curl --location --request GET 'https://api.sandbox.tarabutgateway.io/v1/providers' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
import requests
import json
url = "https://api.sandbox.tarabutgateway.io/v1/providers"
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/v1/providers")
.method("GET")
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
Response Fields
Sample Response (200 Success)
{
"providers": [
{
"providerId": "BANKA",
"name": "BANKA",
"displayName": "BANKA",
"logoUrl": "http://BANKA.com",
"countryCode": "BHR",
"aisStatus": "UNAVAILABLE",
"pisStatus": "AVAILABLE"
},
{
"providerId": "BANKB",
"name": "BANKB",
"displayName": "BANKB",
"logoUrl": "http://BANKB.com",
"countryCode": "BHR",
"aisStatus": "AVAILABLE",
"pisStatus": "UNAVAILABLE"
}
]
}
Field | Type | Description |
---|---|---|
providerId | string | Bank's unique id configured at TG. |
name | string | Name of the bank. |
displayName | string | Display name of the bank. |
logoUrl | string | URL to retrieve the logo of the bank. |
countryCode | string | The Country code providerId is registered in. |
aisStatus | string | CONNECT's status eg : AVAILABLE,UNAVAILABLE |
pisStatus | string | PAY's status, eg : AVAILABLE,UNAVAILABLE |
AIS/PIS Status
Status | Description |
---|---|
AVAILABLE | Connect/PAY is supported by TG for the bank |
UNAVAILABLE | Connect/PAY is not supported at TG for the bank |
Connect
Get permissioned access to bank accounts. Retrieve account and enriched transaction data.
Connect APIs include the following endpoints:
Description | Endpoint |
---|---|
Create Intent | POST /accountInformation/v1/intent |
List Accounts | GET /accountInformation/v1/accounts |
Get Account Holder Name | GET /accountInformation/v1/accounts/{accountId} |
List Transactions | GET /accountInformation/v1/accounts/{accountId}/transactions |
List Raw Transactions | GET /accountInformation/v1/accounts/{accountId}/rawtransactions |
Country Support
Country Support: The environment URLs differ by country.
Ensure to use the correct URL for all requests. Refer Environment URLs section.
Bahrain
Create Intent
POST /accountInformation/v1/intent
enables you to have your users initiate the account linking process by creating an intent.
The API should be called from your backend/server and it returns a connect url, which starts the consent journey for an end-user.
Note: An intent is not complete until the user authorises consent to access their account information at their bank.
Request Url
POST /accountInformation/v1/intent
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Body
Sample Request
curl --location --request POST 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"user":{
"customerUserId": "7982364",
"email": "some@email.com",
"firstName": "John",
"lastName": "Snow",
"userIdentifier": {
"type": "BH.CPR",
"value": "332633423"
}
},
"consent":{
"providerId": "NBOB"
},
"redirectUrl": "http://override.me/notDefault"
}'
import requests
import json
url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent"
payload = json.dumps({
"user": {
"customerUserId": "7982364",
"email": "some@email.com",
"firstName": "John",
"lastName": "Snow",
"userIdentifier": {
"type": "BH.CPR",
"value": "332633423"
}
},
"consent":{
"providerId": "NBOB"
},
"redirectUrl": "http://override.me/notDefault"
})
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"user\":{\n \"customerUserId\": \"7982364\", \n \"email\": \"some@email.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Snow\",\n \"userIdentifier\": {\n \"type\": \"BH.CPR\",\n \"value\": \"332633423\"\n }\n },\n \"redirectUrl\": \"http://override.me/notDefault\",\n \"consent\":{\n \"providerId\": \"NBOB\"\n }\n}");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent")
.method("POST", body)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""user"":{" + "\n" +
@" ""customerUserId"": ""7982364"", " + "\n" +
@" ""email"": ""some@email.com""," + "\n" +
@" ""firstName"": ""John""," + "\n" +
@" ""lastName"": ""Snow""," + "\n" +
@" ""userIdentifier"": {" + "\n" +
@" ""type"": ""BH.CPR""," + "\n" +
@" ""value"": ""332633423""" + "\n" +
@" }" + "\n" +
@" }," + "\n" +
@" ""consent"":{" + "\n" +
@" ""providerId"": ""NBOB""" + "\n" +
@" }," + "\n" +
@" ""redirectUrl"": ""http://override.me/notDefault""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field | Type | Description |
---|---|---|
user | Object required |
Developer managed user context |
customerUserId | string required |
Unique user identification managed by TPP. This must match the X-TG-CustomerUserId header value provided when creating the auth token (see Generate Access Token) Must be less than 40 characters |
string optional |
Valid email of the user maintained by TPP (This field is required if 'userIdentifier' is null) | |
firstName | string required |
First name of the user 60 characters max |
lastName | string required |
Last name of the user 60 characters max |
userIdentifier | Object optional |
Natural identification of user maintained by TPP (This field is required if 'email' is null) |
type | string required |
One of TG supported national identification schema. |
value | string required |
Value of national identification. 60 characters max |
consent | Object optional |
Additional details on the consent |
providerId | string optional |
Unique identification of the provider (see Providers) Provide this identifier to skip the bank selection screen in the Connect flow. 3 to 8 characters length |
redirectUrl | string required |
Redirect URL for the current session (must be a valid https url, including scheme and the one confirgured in TG Console) |
Response Fields
Sample Response (200 Success)
{
"connectUrl": "https://connect.sandbox.tarabutgateway.io/launch/?....",
"intentId": "092d24cc-4691-460d-a33b-f54f0b26403c",
"expiry": "2022-04-06T16:30:00Z"
}
connectUrl field must be used to initiate consent journey, which is to authorise and complete the account linking flow.
Once the linking is completed TG will make a callback to the redirect url used during intent creation.
Field | Type | Description |
---|---|---|
connectUrl | string | The url that needs to be invoked to complete the consent authorisation. |
intentId | string | The unique intent ID (generated by TG) for every linking request. |
expiry | dateTime | Expiry of the intent before which the redirect URL has to be used. |
Consent Journey via Connect
A successfulPOST /accountInformation/v1/intent
call returns the Connect URL. The Connect URL loads a web view that guides your end user through the consent journey. Users choose their provider and are automatically directed to authenticate and authorise consent.
The Connect journey has the following basic steps -
- Select a provider
- Review Permissions
- Redirect to provider
- Authenticate and Authorise at the provider
- Redirect to your app
Looking to build your own provider screen?
To skip the provider list, include the providerId in the Create Intent call. This allows the generation of the Connect URL with Step 2 outlined above.
Get Intent
GET /accountInformation/v1/intent/{intentId}
enables you to get information about existing intents.
GET /accountInformation/v1/intent/{intentId}
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Path Parameters
Path Parameter Name | Type | Description |
---|---|---|
intentId | String | The ID of the intent. |
Sample Request
curl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8"
payload={}
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Response Fields
Sample Response (200 Success)
{
"intentId": "65b56744-719b-4cc7-870d-034b158056c8",
"providerId": "BLUE",
"intentStatus": "COMPLETED"
}
Field | Type | Description |
---|---|---|
intentId | string | The ID of the intent. |
providerId | string | Unique identifier to represent a provider/bank. |
intentStatus | string | Status of the intent, e.g. CREATED, INITIATED,CONSENT_INITIATED, CONSENT_REJECTED,COMPLETED, UNKNOWN. |
Intent Status
Status | Description |
---|---|
CREATED | Initial status of the intent Available post a successful Create Intent call once the Connect URL is generated. |
INITIATED | Connect URL has been consumed/invoked |
CONSENT_INITIATED | User is redirected to the provider to authorise consent |
CONSENT_REJECTED | User rejects consent at the provider |
COMPLETED | User authorises consent at the provider |
List Accounts
GET /accountInformation/v1/accounts
enables you to list accounts for the user by providing the required parameters listed below.
Note: Only accounts that have been linked and given consent to be fetched will be listed in the response (see Create Intent).
Request Url
GET /accountInformation/v1/accounts
Request Headers
Sample Request
curl --location --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts"
payload = ""
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json',
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Response Fields
Sample Response (200 Success)
{
"accounts": [
{
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"accountProductType": "SAVINGS",
"accountDescription": "John Snow's savings account",
"providerId": "NBOB",
"maskedAccountNumber": "******1234",
"identifiers":[
{
"type": "IBAN"
"value": "string"
}
],
"balances": [
{
"type": "AVAILABLE",
"amount": {
"value": 123.123,
"currency": "BHD"
}
}
],
"lastUpdatedDateTime": "2021-12-22T01:59:30.208+00:00",
"links": [
{
"rel": "TRANSACTIONS",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions"
}
]
}
]
}
Field | Type | Description |
---|---|---|
accounts | Object[] | Array of account objects for a given account. |
accountId | string | Unique account ID (generated by TG) for every account that is linked. |
accountProductType | string | Type of account product, e.g. SAVINGS, CURRENT, DEPOSIT, CREDIT_CARD, CHARGE_CARD. |
accountDescription | string | Description of the account (supplied by the bank). |
providerId | string | Unique identifier to represent a provider/bank. |
maskedAccountNumber | string | Masked account number from the bank, with only last four digits shown. |
identifiers | Object[] | Coming soon Array of account identifiers provided by the bank. This may include IBAN, maskedPAN |
type | string | Type of identifier- IBAN, maskedPAN |
value | string | Identifier value. |
balances | Object[] | Array of account balance objects. |
type | string | Account balance type, e.g. AVAILABLE, OUTSTANDING. |
amount | Money | Account balance amount. |
lastUpdatedDateTime | string | Timestamp of when the account was last updated in DateTime format. |
links | Link[] | Array of Link objects for granular account details, e.g. TRANSACTIONS. |
Get Account Holder Name
GET /accountInformation/v1/accounts/{accountId}
enables you to fetch account holder name for a given account id.
Note: Only accounts that have been linked and given consent to be fetched will be listed in the response (see Create Intent).
Request Url
GET /accountInformation/v1/accounts/{accountId}
Request Headers
Sample Request
curl --location --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}"
payload = ""
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json',
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Response Fields
Sample Response (200 Success)
{
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"accountHolderName": "Mohammed Ahmed Abdulla",
"nickname": "Abdulla"
}
Field | Type | Description |
---|---|---|
accountId | string | Unique account ID (generated by TG) for every account that is linked. The identifier is returned in List Accounts response. |
accountHolderName | string | Comma separated list of full names of the account holder. In case of a joint account, it will include all account holder names. |
nickname | string | Nickname. |
List Account Transactions
GET /accountInformation/v1/accounts/{accountId}/transactions
enables you to fetch transactions for a given account ID by providing the required parameters listed below.
Request Url
GET /accountInformation/v1/accounts/{accountId}/transactions
Request Header
Header Key | Header Value | Notes |
---|---|---|
Content-Type | application/json | |
Authorization Bearer | <your_access_token> |
Token will contain the user identifier |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Parameters
Parameter Name | Type | Description |
---|---|---|
page | Integer optional |
Desired results page number (defaults to 1). |
fromBookingDateTime | string optional |
Start timestamp for transaction request in DateTime format. |
toBookingDateTime | string optional |
End timestamp for transaction request in DateTime format. |
Request Path Parameters
Path Parameter Name | Type | Description |
---|---|---|
accountId | string required |
TG account ID to request transactions for. The identifier is returned in List Accounts response. |
Sample Request
curl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4"
payload={}
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Response Fields
Sample Response (200 Success)
{
"transactions": [
{
"transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"providerId": "NBOB",
"transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
"category": {
"group": "Expense",
"name": "Entertainment & Leisure"
},
"merchant": {
"name": "NETFLIX.COM"
},
"creditDebitIndicator": "DEBIT",
"amount": {
"value": 14.99,
"currency": "BHD"
},
"bookingDateTime": "2021-12-22T01:59:30.208+00:00"
}
],
"meta": {
"totalCountOfRecords": 100,
"totalCountOfPages": 10,
"pageNumber": 4,
"pageSize": 10
},
"links": [
{
"rel": "FIRST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=1"
},
{
"rel": "PREVIOUS",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=3"
},
{
"rel": "NEXT",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=5"
},
{
"rel": "LAST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=10"
}
]
}
Note: In the sample response JSON, the pagination Meta object indicates that there are 10 records per page (pageSize). Only one transaction is shown here in order to keep this example response as succinct as possible.
Field | Type | Description |
---|---|---|
transactions | Object[] | Array of transaction objects for a given account. |
transactionId | string | Unique transaction ID (generated by TG) for every transaction. |
accountId | string | Account ID that the transaction is linked to (provided as path parameter). |
providerId | string | Unique identifier to represent a provider/bank. |
transactionDescription | string | Description of the transaction provided by the bank. |
category | Object | Internally generated category object for the transaction. |
group | string | Top level category group. enum: Category Group |
name | string | Main category name. enum: Categories |
merchant | Object nullable |
Internally generated merchant object for the transaction. |
name | string | Name of the merchant in the transaction. |
creditDebitIndicator | string | Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT. |
amount | Money | Transaction amount. |
bookingDateTime | string | Timestamp of when the transaction was booked in DateTime format. |
meta | Object[] | Pagination and query metadata object. |
fromBookingDateTime | string | Start timestamp for transaction request in DateTime format. |
toBookingDateTime | string | End timestamp for transactions request in DateTime format. |
totalCountOfRecords | Integer | Total count of records. |
totalCountOfPages | Integer | Total count of pages for the given page size. |
pageNumber | Integer | Current page number. |
pageSize | Integer | Number of records returned per page. |
links | Link[] | Array of Link objects for pagination, e.g. FIRST, LAST, PREVIOUS, NEXT. |
List Account Raw Transactions
GET /accountInformation/v1/accounts/{accountId}/rawtransactions
enables you to fetch transactions for a given account ID that have not been enriched by providing the required parameters listed below.
Request Header
Header Key | Header Value | Notes |
---|---|---|
Content-Type | application/json | |
Authorization Bearer | <your_access_token> |
Token will contain the user identifier |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Url
GET /accountInformation/v1/accounts/{accountId}/rawtransactions
Request Parameters
Parameter Name | Type | Description |
---|---|---|
page | Integer optional |
Desired results page number (defaults to 1). |
fromBookingDateTime | string optional |
Start timestamp for transaction request in DateTime format. |
toBookingDateTime | string optional |
End timestamp for transaction request in DateTime format. |
Request Path Parameters
Path Parameter Name | Type | Description |
---|---|---|
accountId | string required |
TG account ID to request transactions for. |
Sample Request
curl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4"
payload={}
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Response Fields
Sample Response (200 Success)
{
"transactions": [
{
"transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"providerId": "NBOB",
"transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
"creditDebitIndicator": "DEBIT",
"amount": {
"value": 14.99,
"currency": "BHD"
},
"bookingDateTime": "2021-12-22T01:59:30.208+00:00"
}
],
"meta": {
"totalCountOfRecords": 100,
"totalCountOfPages": 10,
"pageNumber": 4,
"pageSize": 10
},
"links": [
{
"rel": "FIRST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=1"
},
{
"rel": "PREVIOUS",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=3"
},
{
"rel": "NEXT",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=5"
},
{
"rel": "LAST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=10"
}
]
}
Note: In the sample response JSON, the pagination Meta object indicates that there are 10 records per page (pageSize), however we have only shown one transaction here in order to keep this example response as succinct as possible.
Field | Type | Description |
---|---|---|
transactions | Object[] | Array of transaction objects for a given account. |
transactionId | string | Unique transaction ID (generated by TG) for every transaction. |
accountId | string | Account ID that the transaction is linked to (provided as path parameter). |
providerId | string | Unique identifier to represent a provider/bank. |
transactionDescription | string | Description of the transaction provided by the bank. |
creditDebitIndicator | string | Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT. |
amount | Money | Transaction amount. |
bookingDateTime | string | Timestamp of when the transaction was booked in DateTime format. |
meta | Object[] | Pagination and query metadata object. |
fromBookingDateTime | string | Start timestamp for transaction request in DateTime format. |
toBookingDateTime | string | End timestamp for transactions request in DateTime format. |
totalCountOfRecords | Integer | Total count of records. |
totalCountOfPages | Integer | Total count of pages for the given page size. |
pageNumber | Integer | Current page number. |
pageSize | Integer | Number of records returned per page. |
links | Link[] | Array of Link objects for pagination, e.g. FIRST, LAST, PREVIOUS, NEXT. |
Saudi Arabia
Get permissioned access to bank accounts. Retrieve account and enriched transaction data.
Connect APIs include the following endpoints:
Description | Endpoint |
---|---|
Create Intent | POST /accountInformation/v1/intent |
List Accounts | GET /accountInformation/v1/accounts |
Get Account Holder Name | GET /accountInformation/v1/accounts/{accountId} |
List Transactions | GET /accountInformation/v1/accounts/{accountId}/transactions |
List Raw Transactions | GET /accountInformation/v1/accounts/{accountId}/rawtransactions |
Country Support
Country Support: The environment URLs differ by country.
Ensure to use the correct URL for all requests. Refer Environment URLs section.
Create Intent
POST /accountInformation/v1/intent
enables you to have your users initiate the account linking process by creating an intent.
The API should be called from your backend/server and it returns a connect url, which starts the consent journey for an end-user.
Note: An intent is not complete until the user authorises consent to access their account information at their bank.
Request Url
POST /accountInformation/v1/intent
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Body
Sample Request
shell curl --location --request POST 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent' \ --header 'Authorization: Bearer <your_access_token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "user": { "customerUserId": "7982364", "email": "some@email.com "firstName": "John", "lastName": "Snow", }, "consent":{ "providerId": "SNB" }, "redirectUrl": "http://override.me/notDefault" }'
import requests
import json
url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent"
payload = json.dumps({
"user": {
"customerUserId": "7982364",
"email": "some@email.com",
"firstName": "John",
"lastName": "Snow"
},
"consent":{
"providerId": "NBOB"
},
"redirectUrl": "http://override.me/notDefault"
})
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"user\":{\n \"customerUserId\": \"7982364\", \n \"email\": \"some@email.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Snow\",\n \"userIdentifier\": {\n \"type\": \"BH.CPR\",\n \"value\": \"332633423\"\n }\n },\n \"redirectUrl\": \"http://override.me/notDefault\",\n \"consent\":{\n \"providerId\": \"NBOB\"\n }\n}");
Request request = new Request.Builder()
.url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent")
.method("POST", body)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""user"":{" + "\n" +
@" ""customerUserId"": ""7982364"", " + "\n" +
@" ""email"": ""some@email.com""," + "\n" +
@" ""firstName"": ""John""," + "\n" +
@" ""lastName"": ""Snow""," + "\n" +
@" ""userIdentifier"": {" + "\n" +
@" ""type"": ""BH.CPR""," + "\n" +
@" ""value"": ""332633423""" + "\n" +
@" }" + "\n" +
@" }," + "\n" +
@" ""consent"":{" + "\n" +
@" ""providerId"": ""NBOB""" + "\n" +
@" }," + "\n" +
@" ""redirectUrl"": ""http://override.me/notDefault""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field | Type | Description |
---|---|---|
user | Object required |
Developer managed user context |
customerUserId | string required |
Unique user identification managed by TPP. This must match the X-TG-CustomerUserId header value provided when creating the auth token (see Generate Access Token) Must be less than 40 characters |
string optional |
Valid email of the user maintained by TPP (This field is required if 'userIdentifier' is null) | |
firstName | string required |
First name of the user 60 characters max |
lastName | string required |
Last name of the user 60 characters max |
consent | Object optional |
Additional details on the consent |
providerId | string optional |
Unique identification of the provider (see Available Providers) Provide this identifier to skip the bank selection screen in the Connect flow. 3 to 8 characters length |
redirectUrl | string required |
Redirect URL for the current session (must be a valid https url, including scheme and the one configured in TG Developer Portal) |
Response Fields
Sample Response (200 Success)
{
"connectUrl": "https://connect.sau.tarabutgateway.io/launch/?.....",
"intentId": "092d24cc-4691-460d-a33b-f54f0b26403c",
"expiry": "2022-04-06T16:30:00Z"
}
connectUrl field must be used to initiate consent journey, which is to authorise and complete the account linking flow.
Once the linking is completed TG will make a callback to the redirect url used during intent creation.
Field | Type | Description |
---|---|---|
connectUrl | string | The url that needs to be invoked to complete the consent authorisation. |
intentId | string | The unique intent ID (generated by TG) for every linking request. |
expiry | dateTime | Expiry of the intent before which the redirect URL has to be used. |
Consent Journey via Connect
A successfulPOST /accountInformation/v1/intent
call returns the Connect URL. The Connect URL loads a web view that guides your end user through the consent journey. Users choose their provider and are automatically directed to authenticate and authorise consent.
The Connect journey has the following basic steps -
- Select a provider
- Review Permissions
- Redirect to provider
- Authenticate and Authorise at the provider
- Redirect to your app
Looking to build your own provider screen?
To skip the provider list, include the providerId in the Create Intent call. This allows the generation of the Connect URL with Step 2 outlined above.
Get Intent
GET /accountInformation/v1/intent/{intentId}
enables you to get information about existing intents.
GET /accountInformation/v1/intent/{intentId}
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Path Parameters
Path Parameter Name | Type | Description |
---|---|---|
intentId | String | The ID of the intent. |
Sample Request
curl --location -g --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8"
payload={}
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/intent/65b56744-719b-4cc7-870d-034b158056c8");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Response Fields
Sample Response (200 Success)
{
"intentId": "65b56744-719b-4cc7-870d-034b158056c8",
"providerId": "BLUE",
"intentStatus": "COMPLETED"
}
Field | Type | Description |
---|---|---|
intentId | string | The ID of the intent. |
providerId | string | Unique identifier to represent a provider/bank. |
intentStatus | string | Status of the intent, e.g. CREATED, INITIATED,CONSENT_INITIATED, CONSENT_REJECTED,COMPLETED, UNKNOWN. |
Intent Status
Status | Description |
---|---|
CREATED | Initial status of the intent Available post a successful Create Intent call once the Connect URL is generated. |
INITIATED | Connect URL has been consumed/invoked |
CONSENT_INITIATED | User is redirected to the provider to authorise consent |
CONSENT_REJECTED | User rejects consent at the provider |
COMPLETED | User authorises consent at the provider |
List Accounts
GET /accountInformation/v1/accounts
enables you to list accounts for the user by providing the required parameters listed below.
Note: Only accounts that have been linked and given consent to be fetched will be listed in the response (see Create Intent).
Request Url
GET /accountInformation/v1/accounts
Request Headers
Sample Request
curl --location --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts"
payload = ""
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json',
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
.url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Response Fields
Sample Response (200 Success)
{
"accounts": [
{
"accountId": "6549b0dd-27a1-3f5b-ab2a-9a83d8245d16",
"accountProductType": "SAVINGS",
"accountDescription": "John Doe - SAR Savings",
"providerId": "BLUE",
"maskedAccountNumber": "******************8527",
"identifiers":[
{
"type": "IBAN"
"value": "string"
}
],
"balances": [
{
"type": "AVAILABLE",
"amount": {
"value": 123.13,
"currency": "SAR"
}
}
],
"lastUpdatedDateTime": "2021-12-22T01:59:30.208+00:00",
"links": [
{
"rel": "TRANSACTIONS",
"href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/6549b0dd-27a1-3f5b-ab2a-9a83d8245d16/transactions"
}
]
}
]
}
Field | Type | Description |
---|---|---|
accounts | Object[] | Array of account objects for a given account. |
accountId | string | Unique account ID (generated by TG) for every account that is linked. |
accountProductType | string | Type of account product, e.g. SAVINGS, CURRENT, DEPOSIT, CREDIT_CARD, CHARGE_CARD. |
accountDescription | string | Description of the account (supplied by the bank). |
providerId | string | Unique identifier to represent a provider/bank. |
maskedAccountNumber | string | Masked account number from the bank, with only last four digits shown. |
identifiers | Object[] | Coming soon Array of account identifiers provided by the bank. This may include IBAN, maskedPAN |
type | string | Type of identifier- IBAN, maskedPAN |
value | string | Identifier value. |
balances | Object[] | Array of account balance objects. |
type | string | Account balance type, e.g. AVAILABLE, OUTSTANDING. |
amount | Money | Account balance amount. |
lastUpdatedDateTime | string | Timestamp of when the account was last updated in DateTime format. |
links | Link[] | Array of Link objects for granular account details, e.g. TRANSACTIONS. |
Get Account Holder Name
GET /accountInformation/v1/accounts/{accountId}
enables you to fetch account holder name for a given account id.
Note: Only accounts that have been linked and given consent to be fetched will be listed in the response (see Create Intent).
Request Url
GET /accountInformation/v1/accounts/{accountId}
Request Headers
Sample Request
curl --location --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}"
payload = ""
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json',
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
.url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the user identifier |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Response Fields
Sample Response (200 Success)
{
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"accountHolderName": "Mohammed Ahmed Abdulla",
"nickname": "Abdulla"
}
Field | Type | Description |
---|---|---|
accountId | string | Unique account ID (generated by TG) for every account that is linked. The identifier is returned in List Accounts response. |
accountHolderName | string | Comma separated list of full names of the account holder. In case of a joint account, it will include all account holder names. |
nickname | string | Nickname. |
List Account Transactions
GET /accountInformation/v1/accounts/{accountId}/transactions
enables you to fetch transactions for a given account ID by providing the required parameters listed below.
All transactions are enriched with enriched attributes from TG's Insights service that provides category and merchant details.
Find details of categorisation and merchant enrichment here.
Request Url
GET /accountInformation/v1/accounts/{accountId}/transactions
Request Header
Header Key | Header Value | Notes |
---|---|---|
Content-Type | application/json | |
Authorization Bearer | <your_access_token> |
Token will contain the user identifier |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Parameters
Parameter Name | Type | Description |
---|---|---|
page | Integer optional |
Desired results page number (defaults to 1). |
fromBookingDateTime | string optional |
Start timestamp for transaction request in DateTime format. |
toBookingDateTime | string optional |
End timestamp for transaction request in DateTime format. |
Request Path Parameters
Path Parameter Name | Type | Description |
---|---|---|
accountId | string required |
TG account ID to request transactions for. The identifier is returned in List Accounts response. |
Sample Request
curl --location -g --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4"
payload={}
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=4");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Response Fields
Sample Response (200 Success)
{
"transactions": [
{
"transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"providerId": "NBOB",
"transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
"category": {
"group": "Expense",
"name": "Entertainment & Leisure"
},
"merchant": {
"name": "NETFLIX.COM"
},
"creditDebitIndicator": "DEBIT",
"amount": {
"value": 14.99,
"currency": "BHD"
},
"bookingDateTime": "2021-12-22T01:59:30.208+00:00"
}
],
"meta": {
"totalCountOfRecords": 100,
"totalCountOfPages": 10,
"pageNumber": 4,
"pageSize": 10
},
"links": [
{
"rel": "FIRST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=1"
},
{
"rel": "PREVIOUS",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=3"
},
{
"rel": "NEXT",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=5"
},
{
"rel": "LAST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=10"
}
]
}
Note: In the sample response JSON, the pagination Meta object indicates that there are 10 records per page (pageSize). Only one transaction is shown here in order to keep this example response as succinct as possible.
Field | Type | Description |
---|---|---|
transactions | Object[] | Array of transaction objects for a given account. |
transactionId | string | Unique transaction ID (generated by TG) for every transaction. |
accountId | string | Account ID that the transaction is linked to (provided as path parameter). |
providerId | string | Unique identifier to represent a provider/bank. |
transactionDescription | string | Description of the transaction provided by the bank. |
category | Object | Internally generated category object for the transaction. |
group | string | Top level category group. enum: Category Group |
name | string | Main category name. enum: Categories |
merchant | Object nullable |
Internally generated merchant object for the transaction. |
name | string | Name of the merchant in the transaction. |
creditDebitIndicator | string | Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT. |
amount | Money | Transaction amount. |
bookingDateTime | string | Timestamp of when the transaction was booked in DateTime format. |
meta | Object[] | Pagination and query metadata object. |
fromBookingDateTime | string | Start timestamp for transaction request in DateTime format. |
toBookingDateTime | string | End timestamp for transactions request in DateTime format. |
totalCountOfRecords | Integer | Total count of records. |
totalCountOfPages | Integer | Total count of pages for the given page size. |
pageNumber | Integer | Current page number. |
pageSize | Integer | Number of records returned per page. |
links | Link[] | Array of Link objects for pagination, e.g. FIRST, LAST, PREVIOUS, NEXT. |
List Account Raw Transactions
GET /accountInformation/v1/accounts/{accountId}/rawtransactions
enables you to fetch transactions for a given account ID that have not been enriched by providing the required parameters listed below.
Request Header
Header Key | Header Value | Notes |
---|---|---|
Content-Type | application/json | |
Authorization Bearer | <your_access_token> |
Token will contain the user identifier |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Url
GET /accountInformation/v1/accounts/{accountId}/rawtransactions
Request Parameters
Parameter Name | Type | Description |
---|---|---|
page | Integer optional |
Desired results page number (defaults to 1). |
fromBookingDateTime | string optional |
Start timestamp for transaction request in DateTime format. |
toBookingDateTime | string optional |
End timestamp for transaction request in DateTime format. |
Request Path Parameters
Path Parameter Name | Type | Description |
---|---|---|
accountId | string required |
TG account ID to request transactions for. |
Sample Request
curl --location -g --request GET 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4"
payload={}
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4")
.method("GET", null)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=4");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Response Fields
Sample Response (200 Success)
{
"transactions": [
{
"transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"providerId": "NBOB",
"transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
"creditDebitIndicator": "DEBIT",
"amount": {
"value": 14.99,
"currency": "BHD"
},
"bookingDateTime": "2021-12-22T01:59:30.208+00:00"
}
],
"meta": {
"totalCountOfRecords": 100,
"totalCountOfPages": 10,
"pageNumber": 4,
"pageSize": 10
},
"links": [
{
"rel": "FIRST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=1"
},
{
"rel": "PREVIOUS",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=3"
},
{
"rel": "NEXT",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=5"
},
{
"rel": "LAST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=10"
}
]
}
Note: In the sample response JSON, the pagination Meta object indicates that there are 10 records per page (pageSize), however we have only shown one transaction here in order to keep this example response as succinct as possible.
Field | Type | Description |
---|---|---|
transactions | Object[] | Array of transaction objects for a given account. |
transactionId | string | Unique transaction ID (generated by TG) for every transaction. |
accountId | string | Account ID that the transaction is linked to (provided as path parameter). |
providerId | string | Unique identifier to represent a provider/bank. |
transactionDescription | string | Description of the transaction provided by the bank. |
creditDebitIndicator | string | Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT. |
amount | Money | Transaction amount. |
bookingDateTime | string | Timestamp of when the transaction was booked in DateTime format. |
meta | Object[] | Pagination and query metadata object. |
fromBookingDateTime | string | Start timestamp for transaction request in DateTime format. |
toBookingDateTime | string | End timestamp for transactions request in DateTime format. |
totalCountOfRecords | Integer | Total count of records. |
totalCountOfPages | Integer | Total count of pages for the given page size. |
pageNumber | Integer | Current page number. |
pageSize | Integer | Number of records returned per page. |
links | Link[] | Array of Link objects for pagination, e.g. FIRST, LAST, PREVIOUS, NEXT. |
Insights
Accepts a list of raw transactions and returns transactions enriched with category and merchant.
Supported APIs are given below
Description | Endpoint |
---|---|
Enrich transactions | POST /ingest/v1/enrich |
Fetch salaries | GET /insights/v1/salary |
Identify salaries | POST /ingest/v1/salary |
Enrich Transactions
POST /ingest/v1/enrich
enables you to have your users transactions enriched with merchant and category.
The API should be called from your backend/server and it returns a list of the requested transactions and enrichment information.
Works with - Coming Soon
Request Url
POST /ingest/v1/enrich
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the enrich: category and enrich: merchant scopes |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Body
Sample Request
curl --location --request POST 'https://api.sandbox.tarabutgateway.io/ingest/v1/enrich' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {valid-tg-token}' \
--data-raw '{
"transactions": [
{
"transactionId": "1",
"transactionDescription": "KHCB Lulu Hyper HIDD BH",
"amount": {
"value": 14.900,
"currency": "BHD"
},
"creditDebitIndicator": "Credit",
"transactionDateTime": "2021-12-22T01:59:30.208+00:00"
},
{
"transactionId": "2",
"transactionDescription": "PURCHASE ALJAZIRA SUPERMARKET",
"amount": {
"value": 3.750,
"currency": "BHD"
},
"creditDebitIndicator": "Credit",
"transactionDateTime": "2021-12-22T01:00:30.208+00:00"
}
],
"accountId": "BH62BLUE00200000008527",
"accountProductType": "account",
"providerId": "KHCB"
}'
import requests
import json
url = "https://api.sandbox.tarabutgateway.io/ingest/v1/enrich"
payload = json.dumps({
"transactions": [
{
"transactionId": "1",
"transactionDescription": "KHCB Lulu Hyper HIDD BH",
"amount": {
"value": 14.900,
"currency": "BHD"
},
"creditDebitIndicator": "Credit",
"transactionDateTime": "2021-12-22T01:59:30.208+00:00"
},
{
"transactionId": "2",
"transactionDescription": "PURCHASE ALJAZIRA SUPERMARKET",
"amount": {
"value": 3.750,
"currency": "BHD"
},
"creditDebitIndicator": "Credit",
"transactionDateTime": "2021-12-22T01:00:30.208+00:00"
}
],
"accountId": "BH62BLUE00200000008527",
"accountProductType": "account",
"providerId": "KHCB"
})
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"transactions\": [\n {\n \"transactionId\": \"1\",\n \"transactionDescription\": \"KHCB Lulu Hyper HIDD BH\",\n \"amount\": {\n \"value\": 14.900,\n \"currency\": \"BHD\"\n },\n \"creditDebitIndicator\": \"Credit\",\n \"transactionDateTime\": \"2021-12-22T01:59:30.208+00:00\"\n },\n {\n \"transactionId\": \"2\",\n \"transactionDescription\": \"PURCHASE ALJAZIRA SUPERMARKET\",\n \"amount\": {\n \"value\": 3.750,\n \"currency\": \"BHD\"\n },\n \"creditDebitIndicator\": \"Credit\",\n \"transactionDateTime\": \"2021-12-22T01:00:30.208+00:00\"\n }\n ],\n \"accountId\": \"BH62BLUE00200000008527\",\n \"accountProductType\": \"account\",\n \"providerId\": \"KHCB\"\n}");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/ingest/v1/enrich")
.method("POST", body)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/ingest/v1/enrich");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""transactions"":[" + "\n" +
@" {" + "\n" +
@" ""transactionId"": ""1"", " + "\n" +
@" ""transactionDescription"": ""KHCB Lulu Hyper HIDD BH""," + "\n" +
@" ""amount"": {" + "\n" +
@" ""value"": "14.900"," + "\n" +
@" ""currency"": ""BHD""" + "\n" +
@" }" + "\n" +
@" ""creditDebitIndicator"": ""Credit""," + "\n" +
@" ""transactionDateTime"": ""2021-12-22T01:59:30.208+00:00""," + "\n" +
@" }," + "\n" +
@" {" + "\n" +
@" ""transactionId"": ""2"", " + "\n" +
@" ""transactionDescription"": ""PURCHASE ALJAZIRA SUPERMARKET""," + "\n" +
@" ""amount"": {" + "\n" +
@" ""value"": "3.750"," + "\n" +
@" ""currency"": ""BHD""" + "\n" +
@" }" + "\n" +
@" ""creditDebitIndicator"": ""Credit""," + "\n" +
@" ""transactionDateTime"": ""2021-12-22T01:00:30.208+00:00""," + "\n" +
@" }" + "\n" +
@" ]," + "\n" +
@" ""accountId"": ""BH62BLUE00200000008527""" + "\n" +
@" ""accountProductType"": ""account""" + "\n" +
@" ""providerId"": ""KHCB""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field | Type | Description |
---|---|---|
transactions | Array required |
List of raw transactions |
transactionId | string required |
Unique identifier of the transaction |
transactionDescription | string required |
Description of the transaction |
amount | Object required |
Information about the amount of the transaction |
value | string required |
Value of the transaction |
currency | string required |
Currency of the transaction |
creditDebitIndicator | string required |
Indicates whether the transaction type is Credit or Debit |
transactionDateTime | dateTime optional |
Date and time that the transaction took place |
accountId | string required |
Unique identifier of the user account |
accountProductType | string required |
Indicates the type of account. Takes 'account' or 'card' |
providerId | string required |
Unique identification of the provider (see Available Providers) 3 to 8 characters length |
Response Fields
Sample Response (200 Success)
[
{
"transactionId": "1",
"categorisation":
{
"group":"Expense",
"category":"Groceries"
},
"merchantName":"KHCB LULU HYPER HIDD",
"transactionType":"merchant"
},
{
"transactionId": "2",
"categorisation":
{
"group":"Expense",
"category":"Groceries"
},
"merchantName":"ALJAZIRA SUPERMARKET",
"transactionType":"merchant"
}
]
Field | Type | Description |
---|---|---|
transactionId | string | Unique identifier of the transaction. |
categorisation | Object | Categorisation information of the transaction. |
group | string | Categorisation group of the transaction. |
category | string | Categorisation category of the transaction. |
merchantName | string | Merchant name for the transaction. |
transactionType | string | Type of transaction. |
Available Providers
The table below details available providers by ID and name.
Provider ID | Provider Name |
---|---|
ABIB | Al Baraka Islamic Bank |
ALSA | Al Salam Bank |
BBKU | Bank of Bahrain and Kuwait |
BIBB | Bahrain Islamic Bank |
BLUE | Blue Bank * |
ESKB | Eskan Bank |
ABCO | Arab Banking Corporation |
FIBH | Ithmaar Bank |
KFHO | Kuwait Finance House (Bahrain) |
KHCB | Khaleeji Commercial Bank |
NBOB | National Bank of Bahrain |
NBOK | National Bank of Kuwait |
SCBL | Standard Chartered Bank |
*Blue Bank is a demo provider only available in Sandbox.
Fetch salaries
GET /insights/v1/salary
enables you to fetch salaries for a given user, for the last 3 months.
This API should be called from your backend/server and it returns a list of salary amounts with bookingDateTime and month.
Works with - insights.salary:list
Request Url
GET /insights/v1/salary
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the insights.salary:list scope |
Request Path Parameters
Path Parameter Name | Type | Description |
---|---|---|
months | Integer optional |
Number of months back from which we want transactions.(defaults to 3, and can range from 1 to 6 months) |
Note: In addition to the above, also include other headers as documented in Request Headers section
Sample Request
curl --location --request GET 'https://api.sandbox.tarabutgateway.io/insights/v1/salary?months=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {valid-tg-token}'
import requests
import json
url = "https://api.sandbox.tarabutgateway.io/insights/v1/salary?months=3"
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/insights/v1/salary?months=3")
.method("GET")
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/insights/v1/salary?months=3");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Response Fields
Sample Response (200 Success)
{
"salaries" : [
{
"salaryAmount": {
"value": "400.0",
"currency":"BHD"
},
"bookingDateTime": "2022-10-01T00:00:00.000Z",
"monthIndicator": 10
},
{
"salaryAmount": {
"value": "405.0",
"currency":"BHD"
},
"bookingDateTime": "2022-09-01T00:00:00.000Z",
"monthIndicator": 9
},
{
"salaryAmount": {
"value": "410.0",
"currency":"BHD"
},
"bookingDateTime": "2022-08-01T00:00:00.000Z",
"monthIndicator": 8
}
]
}
Field | Type | Description |
---|---|---|
salaries | Object[] | Array of Salary objects for a given user. |
salaryAmount | Money | Salary amount. |
bookingDateTime | string | Timestamp of when the transaction was booked in DateTime format. |
monthIndicator | Integer | Month of salary credit. The value for this field starts from 1(1 = January). |
Identify salaries
POST /ingest/v1/salary
enables you to identify salary transactions from a list of transactions
This API should be called from your backend/server and it returns a list of salary amounts with bookingDateTime and month.
Works with - insights.salary:list
Request Url
POST /ingest/v1/salary
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
Token will contain the insights.salary:list scope |
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Body
Sample Request
curl --location --request POST 'https://api.sandbox.tarabutgateway.io/ingest/v1/salary' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {valid-tg-token}' \
--data-raw '{
"accountId": "1028374082309",
"accountType": "account",
"providerId": "BLUE",
"transactions": [
{
"transactionId": "100",
"description": "A SALARY FOR SOMEONE",
"amount": {
"value": 500,
"currency": "BHD"
},
"bookingDateTime": "2023-06-28T11:11:30Z",
"creditDebitIndicator": "Credit"
},
{
"transactionId": "101",
"description": "Fund transfer from XXXX",
"amount": {
"value": 47,
"currency": "BHD"
},
"bookingDateTime": "2023-06-29T10:00:00Z",
"creditDebitIndicator": "Credit"
}
]
}'
import requests
import json
url = "https://api.sandbox.tarabutgateway.io/ingest/v1/salary"
payload = json.dumps({
"accountId": "1028374082309",
"accountType": "account",
"providerId": "BLUE",
"transactions": [
{
"transactionId": "100",
"description": "A SALARY FOR SOMEONE",
"amount": {
"value": 500,
"currency": "BHD"
},
"bookingDateTime": "2023-06-28T11:11:30Z",
"creditDebitIndicator": "Credit"
},
{
"transactionId": "101",
"description": "Fund transfer from XXXX",
"amount": {
"value": 47,
"currency": "BHD"
},
"bookingDateTime": "2023-06-29T10:00:00Z",
"creditDebitIndicator": "Credit"
}
]
})
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"accountId\": \"1028374082309\", \"accountType\": \"account\", \"providerId\": \"BLUE\", \"transactions\": [{\"transactionId\": \"100\", \"description\": \"A SALARY FOR SOMEONE\", \"amount\": {\"value\": 500, \"currency\": \"BHD\"}, \"bookingDateTime\": \"2023-06-28T11:11:30Z\", \"creditDebitIndicator\": \"Credit\"}, {\"transactionId\": \"101\", \"description\": \"Fund transfer from XXXX\", \"amount\": {\"value\": 47, \"currency\": \"BHD\"}, \"bookingDateTime\": \"2023-06-29T10:00:00Z\", \"creditDebitIndicator\": \"Credit\"}]}");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/ingest/v1/salary")
.method("POST", body)
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/ingest/v1/salary");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @""{\"accountId\": \"1028374082309\", \"accountType\": \"account\", \"providerId\": \"BLUE\", \"transactions\": [{\"transactionId\": \"100\", \"description\": \"A SALARY FOR SOMEONE\", \"amount\": {\"value\": 500, \"currency\": \"BHD\"}, \"bookingDateTime\": \"2023-06-28T11:11:30Z\", \"creditDebitIndicator\": \"Credit\"}, {\"transactionId\": \"101\", \"description\": \"Fund transfer from XXXX\", \"amount\": {\"value\": 47, \"currency\": \"BHD\"}, \"bookingDateTime\": \"2023-06-29T10:00:00Z\", \"creditDebitIndicator\": \"Credit\"}]}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field | Type | Description |
---|---|---|
accountId | string required |
Unique identifier of the user account |
accountType | string required |
Indicates the type of account. Takes 'account' or 'card' |
providerId | string required |
Unique identification of the provider (see Available Providers) 3 to 8 characters length |
transactions | Array required |
List of raw transactions |
transactionId | string required |
Unique identifier of the transaction |
description | string required |
Description of the transaction |
amount | Object required |
Information about the amount of the transaction |
value | string required |
Value of the transaction |
currency | string required |
Currency of the transaction |
creditDebitIndicator | string required |
Indicates whether the transaction type is Credit or Debit |
bookingDateTime | dateTime optional |
Date and time that the transaction took place |
Response Fields
Sample Response (200 Success)
{
"accountId": "1028374082309",
"providerId": "BLUE",
"transactions": [
{
"transactionId": "100",
"amount": {
"value": "500.000",
"currency": "BHD"
},
"monthIndicator": 6,
"bookingDateTime": "2023-06-28T11:11:30.000Z"
}
]
}
Field | Type | Description |
---|---|---|
accountId | string | Unique identifier of the user account |
providerId | string | Unique identification of the provider (see Available Providers) 3 to 8 characters length |
transactions | Array |
List of identified salary transactions |
transactionId | string |
Unique identifier of the transaction |
amount | Object |
Information about the amount of the transaction |
value | string |
Value of the transaction |
currency | string |
Currency of the transaction |
monthIndicator | string |
Corresponding month of identified salary |
bookingDateTime | dateTime |
Date and time that the transaction took place |
Payment Initiation
Initiate secure bank to bank payments using TG's Payment Initiation capabilities. Use the APIs below on TG Pay to create an end-to-end payment experience.
Description | Endpoint |
---|---|
Initiate a payment request | POST /paymentInitiation/v1/payments |
Fetch payment status | GET /paymentInitiation/v1/payments/{paymentId} |
Initiate Payment
`Making a POST call to this API enables you to initiate a payment for a given user by providing the required parameters listed below. The API should be called from your backend/server. The response contains a paymentURL and a paymentId for the user to authorise the requested payment.
🇧🇭 In Bahrain
Our service can be used to initiate a Single Domestic Payment via Fawri+. Fawri+ settles transactions in near real-time, up to 30 seconds and are limited to 1000.000 BHD. Other payment types of payment rails, like Fawri, a slower delayed settlement payment method, are currently not supported. TG does not support other payment types, like future-dated and international payments.
🇸🇦 In The Kingdom of Saudi Arabia Payments are not yet supported in the KSAs Open Banking Standard.
Note: A payment request gets created but is not completed till the user authorizes the payment at the bank.
Request Url
POST /paymentInitiation/v1/payments
Request Headers
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
|
Content-Type | application/json | |
X-TG-IdempotencyKey | <idempotency_key> |
Unique request identifier to support idempotency. Must be less that 40 chars. |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Body
Sample Request
curl --location --request POST 'https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--header 'X-TG-IdempotencyKey: <idempotency_key>' \
--data-raw '{
"endToEndId": "239846923",
"paymentAmount": {
"currency": "BHD",
"value": "0.016"
},
"reference": {
"label": "Bill Number",
"value": "655324898230"
},
"user":{
"customerUserId": "7982364",
"email": "some@email.com",
"firstName": "John",
"lastName": "Snow",
"mobile": "093293845833",
"userIdentifier": {
"type": "BH.CPR",
"value": "332633423"
}
}
}'
url = "https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments"
payload = json.dumps({
"endToEndId": "239846923",
"paymentAmount": {
"currency": "BHD",
"value": "0.016"
},
"reference": {
"label": "Bill Number",
"value": "655324898230"
},
"user": {
"customerUserId": "7982364",
"email": "some@email.com",
"firstName": "John",
"lastName": "Snow",
"mobile": "093293845833",
"userIdentifier": {
"type": "BH.CPR",
"value": "332633423"
}
}
})
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json',
'X-TG-IdempotencyKey': '<idempotency_key>'
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client=new OkHttpClient().newBuilder()
.build();
MediaType mediaType=MediaType.parse("application/json");
RequestBody body=RequestBody.create(mediaType,"{\n \"endToEndId\": \"99e88j4b\",\n \"paymentAmount\": {\n \"currency\": \"BHD\",\n \"value\": \"0.016\"\n },\n \"reference\": {\n \"label\": \"Bill Number\",\n \"value\": \"655324898230\"\n }\n}");
Request request=new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments")
.method("POST",body)
.addHeader("Authorization","Bearer <your_access_token>")
.addHeader("Content-Type","application/json")
.addHeader("X-TG-IdempotencyKey","<idempotency_key>")
.build();
Response response=client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("X-TG-IdempotencyKey", "<idempotency_key>");
var body = @"{" + "\n" +
@" ""endToEndId"": ""99e88j4b""," + "\n" +
@" ""paymentAmount"": {" + "\n" +
@" ""currency"": ""BHD""," + "\n" +
@" ""value"": ""0.016""" + "\n" +
@" }," + "\n" +
@" ""reference"": {" + "\n" +
@" ""label"": ""Bill Number""," + "\n" +
@" ""value"": ""655324898230""" + "\n" +
@" }," + "\n" +
@" ""user"": {" + "\n" +
@" ""customerUserId"": ""7982364""," + "\n" +
@" ""email"": ""some@email.com""," + "\n" +
@" ""firstName"": ""John""," + "\n" +
@" ""lastName"": ""Snow""," + "\n" +
@" ""mobile"": ""092999999999""," + "\n" +
@" ""userIdentifier"": {" + "\n" +
@" ""type"": ""BH.CPR""," + "\n" +
@" ""value"": ""332633423""" + "\n" +
@" }" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Field | Type | Description |
---|---|---|
endToEndId | string required |
A unique end to end payment reference that typical reflects in Payee and Payer's statement 6-12 alphanumeric characters with no spaces or special characters |
paymentAmount | Money required |
Payment Amount (with currency). This is the amount that is requested to be paid. Max limit will apply as per configured value for the client |
reference | object required |
This is the reference for the payment being made. It could be any identifier that the user may understand or know. Appears on the TG Pay Review payment screen before the payment is initiated. |
label | string required |
The reference field label. ex: Invoice #, Order Id, Account, etc. Max length is 20 chars, alphanumeric string with only "-","'" and space is allowed |
value | string required |
The actual reference field. ex: OST1235, 73643, Mike's Wallet, etc. Max length is 20 chars, alphanumeric string with only "-","'" and space is allowed |
name | string | if IBAN is provided, the account holder name of the payee IBAN is required to be sent. |
user | object, nullable | User details. |
customerUserId | string, nullable | Customer user id. |
string, nullable | Email of the user. | |
firstName | string, nullable | First name of the user. |
lastName | string, nullable | Last name of the user. |
mobile | string, nullable | Mobile number of the user. |
userIdentifier | object, nullable | User unique identifier. |
type | string, nullable | Type of user national identifier. For example (BH.CPR). |
value | string, nullable | Value of user national identifier. Will be used by bank to identify the user, if not filled in - user will be asked to enter identification on bank side manually |
Note: We only support payment amounts of up to 1000.000 BHD.
Response Fields
Sample Response (200 Success)
{
"paymentUrl": "https://payments.app.sdb.tarabutgateway.io/banks?lt=eyJraWQiOiI3MDkzRjlFQi1GMDhGLTRENDQtOTg1MS01MEU2NDA2REIzNjUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJyZWRpcmVjdCI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9wYXltZW50L2NhbGxiYWNrIiwiaXNzIjoiaHR0cHM6Ly9hcGkuc2RiLnRhcmFidXRnYXRld2F5LmlvIiwibmFtZSI6IjQ4NmE4YTZjLWE2NjEtNDVkMC1hMmQxLWFjZDk0ODBjYWQ5ZSIsInNraW4iOiJsaW5rIiwiaWQiOiI0OGQxYjM3NC05YTMwLTRjNTUtOWZiOS1lNGFiNDkyMGYwNWUiLCJleHAiOjE2MzI2ODUwODcsImlhdCI6MTYzMjY4NDc4N30.Y-Zem35cHuLMm_Ksntcu5vVeN42EdbM3_dj3gHAtUhD9mBmYuWSPPbUmXd05x4IKd0w9Pw-FwwNQ8s44Wzct5kp5OypAEW51ujKWziMctwE6mdseHacJNm4q_k53MdnBaAzzLtctlHHt7FhWeyanDOIeiv5KUgYvgZy1JGDOI8B8lV4NRT0XqtKV77C7lTfgVwTR6pySk3_JrHK7_8GPTuMkQNQ6poCrgYDar-5Kzm3DJ3QBUZRSH_qNuaTXlQ3xtnpCaJMT4Hm05RO1_MQSXrLQZWJrDZJJMz3z70nSxb0VBKZSHchWY-4EFLec7atwPL7SFH0OVMlwq9Z5W3axfw",
"paymentId": "65a2c9f4-7a9d-4c66-98da-83babfb88888",
"endToEndId": "239846923"
}
paymentUrl field must be used to be redirected to TG Pay, which is to authorise and complete the payment flow.
Once the payment is completed TG Pay will make a callback to the default configured redirect url in TG Console
Field | Type | Description |
---|---|---|
paymentId | string | The unique payment Id as generated by Tarabut Gateway for every payment request |
paymentUrl | string | The payment url that needs to be involved to complete the payment authorisation. It embeds all the required payment details in it |
endToEndId | string | The unique end to end Id as provided by the client when initiate the payment |
Errors
No endpoint specific errors. Generic errors will carry details around any bad input parameters passed.
Note: This section list out summary of specific errors for this API. Refer here for generic errors and more detailed explanation.
Check Payment Status
This endpoint can be used to check the status of a payment, as well as to receive payment information such as payment amount, payer account, and other references.
Request Url
GET /paymentInitiation/v1/payments/{paymentId}
Request Headers
Bearer token and auth version have to be provided in header of request.
Header Key | Header Value | Notes |
---|---|---|
Authorization | Bearer <your_access_token> |
|
Content-Type | application/json |
Note: In addition to the above, also include other headers as documented in Request Headers section
Request Path Parameters
Sample Request
curl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}' \
--header 'Authorization: Bearer <Your_access_token>' \
--header 'Content-Type: application/json'
url = "https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}"
payload = {}
headers = {
'Authorization': 'Bearer <Your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
OkHttpClient client=new OkHttpClient().newBuilder()
.build();
Request request=new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}")
.method("GET",null)
.addHeader("Authorization","Bearer <Your_access_token>")
.addHeader("Content-Type","application/json")
.build();
Response response=client.newCall(request).execute();
var client = new RestClient("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <Your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Field | Type | Description |
---|---|---|
paymentId | string required | paymentId of the payment returned as a part of POST /paymentInitiation/v1/payments. |
Response Fields
Sample Response (200 SUCCESS)
{
"paymentId": "a839c12-b00f-42d2-8558-c1a73c05b707",
"endToEndId": "239846923",
"paymentAmount": {
"value": 0.016,
"currency": "BHD"
},
"reference": {
"label": "Bill Number",
"value": "655324898230"
},
"payerAccount": {
"providerId": "BLUE",
"iban": "BH62REDB00200000008527",
"name": "John Doe"
},
"payeeAccount": {
"providerId": "REDB",
"iban": "BH62REDBXXXXXXXXXX8528",
"name": "Hari's Savings"
},
"bankTransactionId": "8e12367-7fcc-414a-aebb-a06d86147f55",
"paymentStatus": "SETTLED",
"isPayerSaved": false,
"initiationDateTime": "2021-10-14T01:59:30.208+00:00",
"lastUpdatedDateTime": "2021-10-14T01:59:30.208+00:00"
}
Field | Type | Description |
---|---|---|
paymentId | string | Unique payment Id as generated by Tarabut Gateway for every payment request. |
endToEndId | string | Unique end to end payment reference id as sent in the request. |
bankTransactionId | string, nullable | Unique transaction id as returned by the payer bank. Some banks show this transaction id as a part of description instead of endtoendId and can be used for reconciliation. |
userId | string, nullable | Unique user id that gets created in TG's system to associate the user context. |
paymentAmount | Money | Payment Amount (with currency). Amount that was requested to be paid. |
reference | string, nullable | This is the reference for the payment being made as sent in the request. |
value | string | The reference field value. |
label | string | The reference field label. |
payerAccount | string, nullable | Payer account details (debtor account) used for initiating the payment. |
providerId | string | Bank identifier of the payer account. |
payerAccountId | string | Unique payer account identifier. If payer saved is true, this can be stored and used to send back in the subsequent request to ease subsequent payment experience. |
maskAcctNumber | string | Masked account number or iban that can be used to display it to the users for payment confirmation or show it for returning user journey to have then select the saved payer account. |
iban | string, nullable | The IBAN number of the payer account. It can be used to initiate refund process. This is not returned unless enabled for. |
payeeAccount | string | Payee account details (creditor account) where the payment was made. |
providerId | string | Bank identifier of the payee account. |
payeeAccountId | string | Unique payee account identifier. |
maskAcctNumber | string | Masked account number or iban of the payee account. |
iban | string, nullable | The IBAN number of the payer account. This is not returned unless enabled for. |
paymentStatus | string | The status of the payment initiated. enum: Payment Status |
isPayerSaved | boolean | If the user chooses to save the payer account, this flag will be set to true. It can |
initiationDateTime | string | Timestamp when the payment request was initiated with TG in DateTime format |
lastUpdatedDateTime | string | Timestamp when the payment was last updated in DateTime format. Typically it gets updated with status upon payment completion. |
Payment Status
paymentStatus | Description |
---|---|
PENDING | Client has initiated the payment. This is the state that gets returned till the payment request is accepted by the payer bank for processing. This is the default state when a POST /paymentInitiation/v1/payments api call is made. |
DECLINED | User has declined the payment consent with TG. This is a terminal status. |
REJECTED | User has rejected, refused or cancelled the payment at the bank during authorization. |
IN_PROGRESS | Payment is authorized and is in processing. |
DEBIT_COMPLETE | Payer Bank is debited. In real time payments, this is a very intermittent state. |
SETTLED | Payee Bank is credited and payment is complete. |
FAILED | A technical error has occurred and payment could not be processed. |
Errors
No endpoint specific errors. Generic errors will carry details around any bad input parameters passed.
Note: This section list out summary of specific errors for this API. Refer here for generic errors and more detailed explanation.
Error Handling & Schema
A detailed list of all the errors thrown by TG APIs. Please refer Error Response in the overview section to understand generic error schema.
Generic Errors
Http Status Code: 400
{
"error":"INVALID_FIELDS",
"errorMessage":"Required fields missing or invalid field or field values sent in the request",
"details":[
{
"fieldName":"paymentAmount.value",
"message":"must not be null"
}
],
"traceId":"233333"
}
These are common errors that can be thrown for any API endpoint.
HTTP Code | error | Description |
---|---|---|
500 | INTERNAL_SERVER_ERROR | Returned when an unexpected error as occurred on TG's end. |
503 | PLANNED_MAINTENANCE | Returned when the services are unavailable due to a planned maintenance. If you are not informed prior about the maintenance, please reach out to TG support team. |
403 | API_ACCESS_DENIED | Access Token used for this API call is not issued with required scope for this API call. Please check your scope configured or requested for the access token. |
401 | UNAUTHORIZED_ACCESS | Access token used is invalid or expired. Regenerate the access token. |
400 | INVALID_REQUEST | Body could not be parsed or invalid content type passed mis-matched. Review your request body & header. |
400 | INVALID_FIELDS | Required fields missing or invalid field or field values sent in the request; This error will also return details object providing details around specific field. Review the input request parameters. |
400 | INVALID_HEADERS | Required header field is missing or invalid in the request; This error will also return details object providing details around specific header field. Review the header parameters |
404 | API_NOT_FOUND | End point does not exist. Re-verify your end point or API url and path parameters. |
Note: API Specific errors are documented along with respective end points above.
Changelog
What's new with TG!
The changelog provides a view of any changes or updates made to the TG APIs and associated products. Keep a track of any enhancements or bug fixes with our regular updates.
Release Account Information APIs
Account Information
Account Information product is launched in Bahrain which enables users and businesses to request for account and categorised transaction information from financial institutions upon end-user consent securely.
March 2022
Release Payment Initiation APIs
Payment Initiation
Payment Initiation product is launched in Bahrain which allows for seamless bank to bank payments for various use cases such as bill payment, checkout, and account to account payments.
October 2021