docs.tarabutgateway.com
Open in
urlscan Pro
157.175.16.140
Public Scan
URL:
https://docs.tarabutgateway.com/
Submission: On June 18 via automatic, source certstream-suspicious — Scanned from DE
Submission: On June 18 via automatic, source certstream-suspicious — Scanned from DE
Form analysis 0 forms found in the DOM
Text Content
NAV
cURL java-OkHttp python-Request C#-RestSharp
* Introduction
* Product Overview
* Payment Initiation Overview
* Account Information Overview
* API Access & Environments
* Environments Overview
* API Protocols
* Request Headers
* Success Response
* Error Response
* Data Types
* Money Schema
* Link Schema
* Versioning
* Backward Compatibility
* Get Started in Sandbox
* Getting Started with Payment Initiation
* Getting Started with Account Information
* Getting your API Keys - Setup
* Generate Token & Make a Payment
* Generate Token & Access Data
* Sandbox Testing
* Simulating Different Redirection flows
* Considerations
* Developer Tools
* Postman Collection
* Authentication APIs
* Generate Access Token
* Provider APIs
* Provider's Coverage
* Get Providers
* Payment Initiation
* Initiate Payment
* Check Payment Status
* Account Information
* Create Intent
* Available Providers
* Get Intent
* List Accounts
* Get Account Holder Name
* List Account Transactions
* Category Group
* Category Name
* List Account Raw Transactions
* Insights
* Enrich Transactions
* Available Providers
* Fetch salaries
* Error Handling & Schema
* Generic Errors
* Enterprise Services
* Changelog
* Sign Up for a Developer Key
* Privacy Policy
INTRODUCTION
Welcome to Tarabut Gateway (TG) API platform documentation. Here you will find
everything you need to build features, apps, and experiences using TG API
services.
All our endpoints follow standard RESTful principles. You will find all the
example request and response payload snippets along with detailed parameters and
field descriptions to get you up and running quickly.
For you to start interacting with our APIs, please sign up for access here. You
will be provided with access to Developer Console where you can create and
manage the API keys and App settings required for the service.
If you have any questions, please email us at developers@tarabutgateway.com
PRODUCT OVERVIEW
Before we get started, let's look at the products that are supported and will
allow you to leverage open banking to its fullest potential.
PAYMENT INITIATION OVERVIEW
> Take away the complexity of bank integrations and deliver a world-class
> product!
Set-up open banking enabled bank to bank payments for a wide range of use cases,
including bill payments, e-commerce checkouts and account funding.
Why TGPay?
* Provides an optimized user experience to review and authorize payments.
* It instantly connects you to our growing network of banks that support
payment initiation.
* Designed to work seamlessly on desktop and mobile devices like iOS and
Android.
* Maintains compliance with changing open banking standards.
Products/Services Endpoints Authentication APIs
Obtain access token which is required for accessing services /auth/v1/token
Provider APIs
Fetch the list of supported banks /v1/providers Payment Initiation
Initiate and manage payments through your App /paymentInitiation/v1/payments
ACCOUNT INFORMATION OVERVIEW
> Easily plug TG Connect to get secure, user consented access to bank account
> balances and transactions and innovate by building unique solutions!
Orchestrate open banking enabled account data access for a variety of use cases
from PFM to Lending.
Account information through TG is simple through our easy to integrate Account
Information APIs and TGConnect - our frontend widget!
Why TGConnect?
* Provides an optimised user experience to review permissions and consent for
data access.
* It instantly connects you to our growing network of banks across region that
support account information.
* Designed to work seamlessly on desktop and mobile devices like iOS and
Android.
* It is secure and maintains compliance with changing open banking standards.
Products/Services Endpoints Authentication APIs
Obtain access token which is required for using the services /auth/v1/token
Provider APIs
Fetch the list of supported banks /v1/providers Account Information
Initiate bank connection and access account balances and transactions
/accountInformation/v1/intent
/accountInformation/v1/accounts
/accountInformation/v1/accounts/{accountId}/transactions
API ACCESS & ENVIRONMENTS
Start by creating an account on Tarabut Gateway Developer Console. Upon
completion of the signup process you will then access the API keys along with
API URL for Sandbox by clicking on "Create API Keys" from the dashboard and
confirming the region. This creates an App - in other terms a project. You can
come back and edit/manage the app settings any time from the console.
These API keys can be used to obtain OAuth2 access token using token endpoint.
The access token must be supplied as a Bearer token within every service API
call made to TG platform.
ENVIRONMENTS OVERVIEW
TG has two environments -
1. Sandbox environment where you try and test your integration without
requiring live bank accounts and
2. Production environment where you will take the integration live for real
users. This environment is fully scalable and designed to work with live
banks.
You can find the API URLs for these environments from console.
A few points to know:
* All the data in the sandbox environment is completely segregated from
production. You cannot migrate a user or any data from sandbox to production.
* The API keys (clientId and clientSecret) will be different for sandbox and
for production.
* All testing should be done in the sandbox environment. Any activity in
production will be billed.
Once you are ready to go to Production, you can request the production keys by
emailing us at sales@tarabutgateway.com.
API PROTOCOLS
The service is made available through Application Programming Interface (API)
endpoints, all of which adhere to REST design principles. Standard HTTP verbs
and status codes are used for requests and response statuses. Request and
response payloads are of JSON format.
To ensure data security and privacy, TG API is served over HTTPS TLS v1.2+
protocol only.
REQUEST HEADERS
The following header attributes are required to be sent for almost all API calls
and the body must have a valid JSON. API specific headers are documented along
with respective APIs.
> Sample Header Attributes
Copy to ClipboardContent-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
Copy to ClipboardHttp 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.
Please Note
Adding new enum values for error and changing the errorMessage is treated as
backward compatible changes. This can happen especially when a generic error is
further refined by creating new error codes. Please practice defensive coding
style while handling error codes.
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
Copy to Clipboard{
"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)
Copy to Clipboard{
"rel": "FIRST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=1"
}
We use a link object to return API references for other related API calls. It
could be for pagination or other related entities.
Field Type Description rel string The relationship of the link. href string The
link to request the resource.
VERSIONING
The API base URL contains a version identifier. The current version is v1.
Tarabut Gateway will support one prior version for a maximum of six months after
the introduction of a new version.
A detailed changelog will be updated from time to time detailing the changes
introduced be it either backward incompatible or compatible changes.
BACKWARD COMPATIBILITY
Tarabut Gateway aims to make integration as seamless as possible for its client
and takes all possible steps to prevent backward-compatibility breaks. In the
scenario where a change is unavoidable, we either create a new endpoint by
renaming the url or updating the version.
Tarabut Gateway considers the following changes to be backwards-compatible or
non-breaking changes:
* Adding new API endpoints
* Adding new optional request parameters to existing API endpoints
* Adding new data elements/properties to existing API response schemas
* Changing the order of elements in the existing API responses.
* Changing the length or format of opaque strings or data elements, such as
reference ids, API identifiers, error messages, and other human-readable
strings.
* Adding new enum values for error is treated as backward compatible changes.
* Adding new event types. - webhook listener should gracefully handle
unfamiliar event types.
GET STARTED IN SANDBOX
Use our APIs to make a single immediate payment or access account information in
just a few steps. Here is how it works-
GETTING STARTED WITH PAYMENT INITIATION
1. Sign up for a developer account at TG Console
2. Create your Client ID and Secret for sandbox in order to access our API
services.
3. Generate Access Token and Initiate Payment by providing payment amount and
an endToEndId.
4. We will provide you with Payment URL to TG Pay which is a simple interface
to select bank, review payment and authorise payment at the bank.
You can quickly get started by using our Postman collection.
GETTING STARTED WITH ACCOUNT INFORMATION
1. Sign up for a developer account at TG Console
2. Create your Client Id and Secret for sandbox in order to access our API
services.
3. Generate Access Token and Create Intent by providing User details.
This will return a URL to TG Connect which is a simple interface for the
user to select bank, review permissions and authenticate with the bank and
selecting accounts.
Sandbox will always redirect to a test bank called Blue bank.
4. Invoke the returned TG Connect URL on your client app for the user to
consent for account access.
5. Fetch account balances and transactions from your server application.
You can quickly get started by using our Postman collection.
GETTING YOUR API KEYS - SETUP
In order to use TG APIs, it is necessary to generate an access token using API
keys (clientId and clientSecret). You can get the API keys by signing up at TG
Console. This is a one time setup. As we generate the API keys, we also create
your first app to get you started quickly!
After successfully setting up an application through TG Console, you can access
the Keys and URL from API Keys menu item.
Be Careful!
Please secure your clientSecret and do not share with anyone or use it on client
side code. It is to be used only on your server side/backend code.
GENERATE TOKEN & MAKE A PAYMENT
You will use both a server and a client-side component to access the TG APIs. A
typical payment flow looks like this:
1. Call POST /auth/v1/token from your server using your API keys to generate an
access token.
2. Call POST /paymentInitiation/v1/payments to initiate a payment which will
return a unique TG Pay payment URL for your user to authorize the payment
from your client app.
3. Upon successful payment authorization, the payment will be initiated and a
unique paymentId will be returned along with paymentStatus. Use Test Account
for your sandbox testing.
4. Store this paymentId along with other details for your future reference or
accessing the payment status details using GET
/paymentInitiation/v1/payments from your server.
Note: We have pre-configured a dummy payee account (aka beneficiary account) in
the sandbox environment for you.
GENERATE TOKEN & ACCESS DATA
You will use both server and a client-side component to access the TG APIs. A
typical account information flow to access data looks like this:
1. Call POST /auth/v1/token from your server using your API keys to generate
access token.
2. Call POST /accountInformation/v1/intent to initiate account linking which
will return a unique TG Connect URL for your user to consent and
authenticate with bank for data access from your client app.
3. Upon successfully connecting a bank, You can now access the accounts,
transactions using GET /accountInformation/v1/accounts and GET
/accountInformation/v1/accounts/{accountId}/transactions respectively from
your server.
SANDBOX TESTING
Tarabut Gateway has created a mock/dummy bank by name "Blue Bank" to help
developers integrate and test the integration.
This is a minimalistic simulated bank experience whereupon initiating the
payment URL and selection of Blue Bank, takes you to the Blue Bank website to
authenticate and authorize the payment.
Please use any four-digit number to authenticate to Blue bank.
SIMULATING DIFFERENT REDIRECTION FLOWS
APP TO APP REDIRECTION
Coming Soon
We are actively working to enhance our Blue Bank application to be available as
an App so that you can test this flow.
APP TO WEB OR WEB TO WEB REDIRECTION
To test the web redirection flow which most banks support, once you select Blue
Bank the widget will automatically redirect to Blue Bank web authentication
page.
DECOUPLED AUTHENTICATION
Sorry, this is not supported today through our current Blue Bank.
Don't worry! TG Pay or the TG Connect widget will handle this and there is no
integration work that will be required at your end.
Learn more about different authentication flow here.
Note: You don't need to worry about any of these during implementation. Our TG
Pay and TG Connect widgets take care of these seamlessly and uses the best
authentication flow based on what is supported by the bank.
CONSIDERATIONS
* Sandbox environment and test accounts is not for real bank simulation and is
purely intended for integration testing in Sandbox!
* Blue Bank is hosted by Tarabut Gateway and is not a real bank. This may not
reflect real bank behavior.
* Blue Bank enables simulation of a basic authentication flow and returns close
to real user's data that cannot be used for variations of actual banks &
accounts.
* It is highly recommended to use real accounts for user acceptance testing in
production before opening up the service for all users.
DEVELOPER TOOLS
POSTMAN COLLECTION
Postman is a convenient tool for a quick and easy way to try out TG APIs without
writing any code. We have created the Postman collection which has pre-formatted
requests of TG API endpoints. It consists of all endpoints that are required to
complete an account information or payment initiation flow. All you have to do
is -
1. Download and install the Postman app
2. Download and import the TG API Endpoints postman collection. Copy this JSON
link and import into Postman
3. Configure the environment with your API keys by adding them as Postman
collection variables.
4. Start using each API as explained in the Get Started guide
Note: You will need to open the payment URL in a browser, as returned by the
POST /paymentInitiation/v1/payment endpoint, to complete the payment flow.
Similarly, you will need to open the connect URL in a browser, as returned by
POST /accountInformation/v1/intent endpoint, to initiate the bank connection
flow.
CONFIGURE ENVIRONMENT AND API KEYS
Once you import the collections, navigate to the Collections tab on the left
sidebar and you can see a folder named Tarabut Gateway API Endpoints that
contains all required APIs. The Collection uses Postman environment variables to
simplify each API request.
>
All what you have to do is:
1. Select the Tarabut Gateway API Collection
2. Click the Variables tab
3. Copy your API keys from TG Console. Update the ClientId and ClientSecret.
4. Save your changes and start making API requests!
Further information on managing Postman environments can be found here.
TIPS AND TRICKS: CODE SNIPPETS
The Postman app has the ability to instantly generate code snippets in numerous
languages and frameworks, so you can make the same request from your
application.
Once you’ve selected an API call, click "Code" on the right, and select your
language from the drop-down list.
AUTHENTICATION APIS
TG uses access tokens to authenticate and authorize API requests. The access
token is provided in the HTTP Authorization header as Authorization: Bearer for
all end points, and is valid for a limited time.
Description Endpoint Fetch access token POST /auth/v1/token
GENERATE ACCESS TOKEN
Fetch access token for your authentication and use to access TG APIs
Works with - Coming Soon
Note: Tarabut Gateway also offers JWTs based authentication. Please reach out to
us for using it.
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
Copy to Clipboardcurl --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"
}'
Copy to Clipboardurl = "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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar 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.
Disclaimer: When introducing Account Information Services, we realised that
scopes need to be mandatory. This may mean that you will need to change the way
you authenticate with us in the future. We will inform you before this change is
made.
RESPONSE FIELDS
> Sample Response (200 Success)
Copy to Clipboard{
"accessToken": "Your_access_token",
"expiresIn": 3600,
"tokenType": "Bearer"
}
Returns the accessToken that needs to be used for TG API authentication.
Field Type Description accessToken string Generated access token that needs to
be used for API access in Authorization header expiresIn integer Validity of
Token in seconds tokenType string "Bearer"
ERRORS
HTTP Code Error Description 403 INVALID_SCOPES Requested product scope is not
available or subscribed for this client id 400 INVALID_API_KEYS Invalid or
missing client id or secret provided 403 API_ACCESS_DENIED Client ID
suspended/blocked
Note: This section list out summary of specific errors for this API. Refer here
for generic errors and more detailed explanation.
PROVIDER APIS
Fetch supported providers along with details. Each Provider entity represents a
financial institution with a distinct login URL.
Note: It is possible that a financial institution might have multiple logins for
different services (or different lines of business). These will be represented
as different providers.
Description Endpoint Fetch Providers GET /v1/providers
PROVIDER'S COVERAGE
TG supports almost all the banking institutions in Bahrain today. We are
actively working to expand our coverage and integrations for UAE and Saudi
Arabia.
GET PROVIDERS
Get a list of all the financial institutions TG can connect to for PISP-related
services. The details about the financial institutions can be used to build an
account selection experience.
Coming soon: - The result will be filtered based on the products and regions
that are enabled for the client and the App. - The result will include providers
for AISP-related services.
Required authentication token scopes
Coming soon
REQUEST PATH
GET /v1/providers
REQUEST HEADERS
No endpoint-specific headers
For the list of headers required in general by TG APIs, click here.
> Sample Request
Copy to Clipboardcurl --location --request GET 'https://api.sandbox.tarabutgateway.io/v1/providers' \
--header 'Authorization: Bearer <Your_access_token>' \
--header 'Content-Type: application/json' \
Copy to Clipboardurl = "https://api.sandbox.tarabutgateway.io/v1/providers"
payload = ""
headers = {
'Authorization': 'Bearer <Your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
Copy to ClipboardOkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/v1/providers")
.method("GET", null)
.addHeader("Authorization", "Bearer <Your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
Copy to Clipboardvar client = new RestClient("https://api.sandbox.tarabutgateway.io/v1/providers");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <Your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
RESPONSE FIELDS
> Sample Response (200 Success)
Copy to Clipboard[
{
"providerId": "NBOB",
"name": "National Bank of Bahrain",
"displayName": "National Bank of Bahrain",
"logoUrl": "https://tg-external-entities.s3.me-south-1.amazonaws.com/NBOB.png",
"countryCode": "BHR",
"status": "ACTIVE"
}
]
List of all the financial institutions TG can connect to for PISP-related
services.
Field Type Description providerId string Unique TG identifier for the provider.
name string The provider or financial institution's official name. displayName
string Shorter version of the provider name. status string The status of the
provider.
Enum : Provider Status logoUrl string The static logo URL of the institution.
Disclaimer: This is the logo of the bank as available in the public domain for
use in the bank selection screen if required. countryCode string Country code of
the provider in ISO 3166-1 alpha-3.
Note: In Sandbox, Bank will be the only supported provider returned.
PROVIDER STATUS
Status Description ACTIVE The provider is integrated with TG. A provider with
this status can, for example, be listed for the end-user to select in the bank
selection experience. INACTIVE The provider is not available. IN_DEVELOPMENT TG
is actively integrating with the provider and it is expected to be ACTIVE soon.
This status can be used, for example, to label a provider as Coming Soon in the
bank selection experience.
ERRORS
No endpoint specific error.
Note: This section lists a summary of specific errors for this API. For a
detailed list of general-purpose errors returned by TG APIs, click here.
PAYMENT INITIATION
Initiate secure bank to bank payments using TG's Payment Initiation
capabilities. Use the APIs below on TG Pay to create an end-to-end payment
experience.
Description Endpoint Initiate a payment request POST
/paymentInitiation/v1/payments Fetch payment status GET
/paymentInitiation/v1/payments/{paymentId}
INITIATE PAYMENT
POST /paymentInitiation/v1/payments enables you to initiate a payment for a
given user by providing the required parameters listed below. The API should be
called from your backend/server, it returns a TG Pay PaymentURL along with a
paymentId for the user to authorize the payment requested
TG Pay API automatically chooses the best and most appropriate payment rail to
make the fastest payment with no or lowest fees to the user. Note: A payment
request gets created but is not completed till the user authorizes the payment
at the bank..
Works with - Coming Soon
REQUEST URL
POST /paymentInitiation/v1/payments
REQUEST HEADERS
Header Key Header Value Notes Authorization Bearer <your_access_token>
Content-Type application/json X-TG-IdempotencyKey <idempotency_key> Unique
request identifier to support idempotency.
Must be less that 40 chars.
Note: In addition to the above, also include other headers as documented in
Request Headers section
REQUEST BODY
> Sample Request
Copy to Clipboardcurl --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"
}
}
}'
Copy to Clipboardurl = "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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar client = new RestClient("https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("X-TG-IdempotencyKey", "<idempotency_key>");
var body = @"{" + "\n" +
@" ""endToEndId"": ""99e88j4b""," + "\n" +
@" ""paymentAmount"": {" + "\n" +
@" ""currency"": ""BHD""," + "\n" +
@" ""value"": ""0.016""" + "\n" +
@" }," + "\n" +
@" ""reference"": {" + "\n" +
@" ""label"": ""Bill Number""," + "\n" +
@" ""value"": ""655324898230""" + "\n" +
@" }," + "\n" +
@" ""user"": {" + "\n" +
@" ""customerUserId"": ""7982364""," + "\n" +
@" ""email"": ""some@email.com""," + "\n" +
@" ""firstName"": ""John""," + "\n" +
@" ""lastName"": ""Snow""," + "\n" +
@" ""mobile"": ""092999999999""," + "\n" +
@" ""userIdentifier"": {" + "\n" +
@" ""type"": ""BH.CPR""," + "\n" +
@" ""value"": ""332633423""" + "\n" +
@" }" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Field Type Description endToEndId string
required A unique end to end payment reference that typical reflects in Payee
and Payer's statement
6-12 alphanumeric characters with no spaces or special characters paymentAmount
Money
required Payment Amount (with currency). This is the amount that is requested to
be paid.
Max limit will apply as per configured value for the client reference object
required This is the reference for the payment being made. It could be any
identifier that the user may understand or know. Appears on the TG Pay Review
payment screen before the payment is initiated. label string
required The reference field label.
ex: Invoice #, Order Id, Account, etc.
Max length is 20 chars, alphanumeric string with only "-","'" and space is
allowed value string
required The actual reference field.
ex: OST1235, 73643, Mike's Wallet, etc.
Max length is 20 chars, alphanumeric string with only "-","'" and space is
allowed payeeAccount object This is the optional Payee account information that
can be passed to dynamically set the payee account information
payeeAccountId string For certain use cases, multiple payee accounts can be
pre-configured. Passing the payee account id will allow to make the payment to
this payee account instead of default.
Alternatively, if the client is using account information service and want to
allow payments within linked bank accounts, or in me2me payment use case where
account needs to be verified first, we can pass the accountId here to which the
payment needs to be made. iban string IBAN of the Payee account
To be used only for Peer 2 peer payments or payout use case (needs explicit
approval and enablement) where payee creation is required at a user level.
name string if iban is provided, the account holder name of the payee iban is
required to be sent. payerAccount object This is the optional Payer account
information that should be passed to preselect the payer's bank account.
Typically gets used in the subsequent payment flow. providerId string
Providing providerID will skip the bank selection screen in TG Pay and directly
take the user to review payment screen. This is typically used when client wants
to implement bank selection at their end instead of one present in TG Pay. It
also needs to be sent in the request when iban is passed as payerAccount field.
payerAccountId string In case of subsequent payment, clients are required to
pass this payerAccountId as returned in response to initial payment. This
simplifies the return user journey by skipping bank and account selection during
payment authorisation/consent flow. iban string IBAN of the Payer account
If the client already has IBAN of the account from which the payment needs to be
made, they can pass this it here. This pre-selects the bank account during
authorisation/consent flow. name string if iban is provided, the account
holder name of the payee iban is required to be sent. user object, nullable User
details. customerUserId string, nullable Customer user id. email string,
nullable Email of the user. firstName string, nullable First name of the
user. lastName string, nullable Last name of the user. mobile string,
nullable Mobile number of the user. userIdentifier object, nullable User
unique identifier. type string, nullable Type of user national
identifier. For example (BH.CPR). value string, nullable Value of user
national identifier. Will be used by bank to identify the user, if not filled in
- user will be asked to enter identification on bank side manually
Note: We only support payment amounts of up to 1000.000 BHD.
RESPONSE FIELDS
> Sample Response (200 Success)
Copy to Clipboard{
"paymentUrl": "https://payments.app.sdb.tarabutgateway.io/banks?lt=eyJraWQiOiI3MDkzRjlFQi1GMDhGLTRENDQtOTg1MS01MEU2NDA2REIzNjUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJyZWRpcmVjdCI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9wYXltZW50L2NhbGxiYWNrIiwiaXNzIjoiaHR0cHM6Ly9hcGkuc2RiLnRhcmFidXRnYXRld2F5LmlvIiwibmFtZSI6IjQ4NmE4YTZjLWE2NjEtNDVkMC1hMmQxLWFjZDk0ODBjYWQ5ZSIsInNraW4iOiJsaW5rIiwiaWQiOiI0OGQxYjM3NC05YTMwLTRjNTUtOWZiOS1lNGFiNDkyMGYwNWUiLCJleHAiOjE2MzI2ODUwODcsImlhdCI6MTYzMjY4NDc4N30.Y-Zem35cHuLMm_Ksntcu5vVeN42EdbM3_dj3gHAtUhD9mBmYuWSPPbUmXd05x4IKd0w9Pw-FwwNQ8s44Wzct5kp5OypAEW51ujKWziMctwE6mdseHacJNm4q_k53MdnBaAzzLtctlHHt7FhWeyanDOIeiv5KUgYvgZy1JGDOI8B8lV4NRT0XqtKV77C7lTfgVwTR6pySk3_JrHK7_8GPTuMkQNQ6poCrgYDar-5Kzm3DJ3QBUZRSH_qNuaTXlQ3xtnpCaJMT4Hm05RO1_MQSXrLQZWJrDZJJMz3z70nSxb0VBKZSHchWY-4EFLec7atwPL7SFH0OVMlwq9Z5W3axfw",
"paymentId": "65a2c9f4-7a9d-4c66-98da-83babfb88888",
"endToEndId": "239846923"
}
> paymentUrl field must be used to be redirected to TG Pay, which is to
> authorise and complete the payment flow.
>
> Once the payment is completed TG Pay will make a callback to the default
> configured redirect url in TG Console
Field Type Description paymentId string The unique payment Id as generated by
Tarabut Gateway for every payment request paymentUrl string The payment url that
needs to be involved to complete the payment authorisation. It embeds all the
required payment details in it endToEndId string The unique end to end Id as
provided by the client when initiate the payment
ERRORS
No endpoint specific errors. Generic errors will carry details around any bad
input parameters passed.
Note: This section list out summary of specific errors for this API. Refer here
for generic errors and more detailed explanation.
CHECK PAYMENT STATUS
This endpoint can be used to check the status of a payment, as well as to
receive payment information such as payment amount, payer account, and other
references.
Works with - Coming Soon
REQUEST URL
GET /paymentInitiation/v1/payments/{paymentId}
REQUEST HEADERS
Bearer token and auth version have to be provided in header of request.
Header Key Header Value Notes Authorization Bearer <your_access_token>
Content-Type application/json
Note: In addition to the above, also include other headers as documented in
Request Headers section
REQUEST PATH PARAMETERS
> Sample Request
Copy to Clipboardcurl --location -g --request GET 'https://api.sandbox.tarabutgateway.io/paymentInitiation/v1/payments/{paymentId}' \
--header 'Authorization: Bearer <Your_access_token>' \
--header 'Content-Type: application/json'
Copy to Clipboardurl = "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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar 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)
Copy to Clipboard{
"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.
Please Note: Tarabut Gateway is reviewing these status working with banks. This
is subject to change during early beta testing cycle.
ERRORS
No endpoint specific errors. Generic errors will carry details around any bad
input parameters passed.
Note: This section list out summary of specific errors for this API. Refer here
for generic errors and more detailed explanation.
ACCOUNT INFORMATION
Connect Bank accounts using TG Connect and gain access to account and
transaction information.
Supported APIs are given below
Description Endpoint Create Intent POST /accountInformation/v1/intent List
Accounts GET /accountInformation/v1/accounts Get Account Holder Name GET
/accountInformation/v1/accounts/{accountId} List Transactions GET
/accountInformation/v1/accounts/{accountId}/transactions List Raw Transactions
GET /accountInformation/v1/accounts/{accountId}/rawtransactions
CREATE INTENT
POST /accountInformation/v1/intent enables you to have your users initiate the
account linking process by creating an intent.
The API should be called from your backend/server and it returns a connect url,
which starts the consent journey for an end-user.
Note: An intent is not complete until the user authorises consent to access
their account information at their bank.
Works with - Coming Soon
REQUEST URL
POST /accountInformation/v1/intent
REQUEST HEADERS
Header Key Header Value Notes Authorization Bearer <your_access_token> Token
will contain the user identifier Content-Type application/json
Note: In addition to the above, also include other headers as documented in
Request Headers section
REQUEST BODY
> Sample Request
Copy to Clipboardcurl --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"
}'
Copy to Clipboardimport 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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar client = new RestClient("https://api.sandbox.tarabutgateway.io/accountInformation/v1/intent");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@" ""user"":{" + "\n" +
@" ""customerUserId"": ""7982364"", " + "\n" +
@" ""email"": ""some@email.com""," + "\n" +
@" ""firstName"": ""John""," + "\n" +
@" ""lastName"": ""Snow""," + "\n" +
@" ""userIdentifier"": {" + "\n" +
@" ""type"": ""BH.CPR""," + "\n" +
@" ""value"": ""332633423""" + "\n" +
@" }" + "\n" +
@" }," + "\n" +
@" ""consent"":{" + "\n" +
@" ""providerId"": ""NBOB""" + "\n" +
@" }," + "\n" +
@" ""redirectUrl"": ""http://override.me/notDefault""" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Field Type Description user Object
required Developer managed user context customerUserId string
required Unique user identification managed by TPP. This must match the
X-TG-CustomerUserId header value provided when creating the auth token (see
Generate Access Token)
Must be less than 40 characters email string
optional Valid email of the user maintained by TPP (This field is required if
'userIdentifier' is null) firstName string
required First name of the user
60 characters max lastName string
required Last name of the user
60 characters max userIdentifier Object
optional Natural identification of user maintained by TPP (This field is
required if 'email' is null) type string
required One of TG supported national identification schema value string
required Value of national identification
60 characters max consent Object
optional Additional details on the consent providerId string
optional Unique identification of the provider (see Available Providers)
3 to 8 characters length redirectUrl string
required Redirect URL for the current session (must be a valid https url,
including scheme and the one confirgured in TG Console)
RESPONSE FIELDS
> Sample Response (200 Success)
Copy to Clipboard{
"connectUrl": "https://accounts.app.sdb.tarabutgateway.io/confirm?lt=token",
"intentId": "092d24cc-4691-460d-a33b-f54f0b26403c",
"expiry": "2022-04-06T16:30:00Z"
}
> connectUrl field must be used to initiate consent journey, which is to
> authorise and complete the account linking flow.
>
> Once the linking is completed TG will make a callback to the redirect url used
> during intent creation.
Field Type Description connectUrl string The url that needs to be invoked to
complete the consent authorisation. intentId string The unique intent ID
(generated by TG) for every linking request. expiry dateTime Expiry of the
intent before which the redirect URL has to be used.
AVAILABLE PROVIDERS
The table below details available providers by ID and name.
Provider ID Provider Name ABIB Al Baraka Islamic Bank ALSA Al Salam Bank BBKU
Bank of Bahrain and Kuwait BIBB Bahrain Islamic Bank BLUE Blue Bank * ESKB Eskan
Bank ABCO Arab Banking Corporation FIBH Ithmaar Bank KFHO Kuwait Finance House
(Bahrain) KHCB Khaleeji Commercial Bank NBOB National Bank of Bahrain NBOK
National Bank of Kuwait SCBL Standard Chartered Bank
*Blue Bank is a demo provider only available in Sandbox.
GET INTENT
GET /accountInformation/v1/intent/{intentId} enables you to get information
about existing intents.
REQUEST URL
GET /accountInformation/v1/intent/{intentId}
REQUEST HEADERS
Header Key Header Value Notes Authorization Bearer <your_access_token> Token
will contain the user identifier Content-Type application/json
Note: In addition to the above, also include other headers as documented in
Request Headers section
REQUEST PATH PARAMETERS
Path Parameter Name Type Description intentId String The ID of the intent.
> Sample Request
Copy to Clipboardcurl --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'
Copy to Clipboardurl = "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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar 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)
Copy to Clipboard{
"intentId": "65b56744-719b-4cc7-870d-034b158056c8",
"providerId": "BLUE",
"intentStatus": "COMPLETED"
}
Field Type Description intentId string The ID of the intent. providerId string
Unique identifier to represent a provider/bank. intentStatus string Status of
the intent, e.g. CREATED, INITIATED, COMPLETED, CONSENT_INITIATED,
CONSENT_REJECTED, UNKNOWN.
LIST ACCOUNTS
GET /accountInformation/v1/accounts enables you to list accounts for the user by
providing the required parameters listed below.
Note: Only accounts that have been linked and given consent to be fetched will
be listed in the response (see Create Intent).
Note: You don't need to worry about any of these during implementation. Our TG
Pay and TG Connect widgets take care of these seamlessly and uses the best
authentication flow based on what is supported by the bank.
Works with - Coming Soon
REQUEST URL
GET /accountInformation/v1/accounts
REQUEST HEADERS
> Sample Request
Copy to Clipboardcurl --location --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
Copy to Clipboardurl = "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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar 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)
Copy to Clipboard{
"accounts": [
{
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"accountProductType": "SAVINGS",
"accountDescription": "John Snow's savings account",
"providerId": "NBOB",
"maskedAccountNumber": "******1234",
"balances": [
{
"type": "AVAILABLE",
"amount": {
"value": 123.123,
"currency": "BHD"
}
}
],
"lastUpdatedDateTime": "2021-12-22T01:59:30.208+00:00",
"links": [
{
"rel": "TRANSACTIONS",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions"
}
]
}
]
}
Field Type Description accounts Object[] Array of account objects for a given
account. accountId string Unique account ID (generated by TG) for every
account that is linked. accountProductType string Type of account product,
e.g. SAVINGS, CURRENT, DEPOSIT, CREDIT_CARD, CHARGE_CARD. accountDescription
string Description of the account (supplied by the bank). providerId string
Unique identifier to represent a provider/bank. maskedAccountNumber string
Masked account number from the bank, with only last four digits shown.
balances Object[] Array of account balance objects. type string Account
balance type, e.g. AVAILABLE, OUTSTANDING. amount Money Account balance
amount. lastUpdatedDateTime string Timestamp of when the account was last
updated in DateTime format. links Link[] Array of Link objects for granular
account details, e.g. TRANSACTIONS.
GET ACCOUNT HOLDER NAME
GET /accountInformation/v1/accounts/{accountId} enables you to fetch account
holder name for a given account id.
Note: Only accounts that have been linked and given consent to be fetched will
be listed in the response (see Create Intent).
Note: You don't need to worry about any of these during implementation. Our TG
Pay and TG Connect widgets take care of these seamlessly and uses the best
authentication flow based on what is supported by the bank.
Works with - Coming Soon
REQUEST URL
GET /accountInformation/v1/accounts/{accountId}
REQUEST HEADERS
> Sample Request
Copy to Clipboardcurl --location --request GET 'https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/{accountId}' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json'
Copy to Clipboardurl = "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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar 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)
Copy to Clipboard{
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"accountHolderName": "Mohammed Ahmed Abdulla",
"nickname": "Abdulla"
}
Field Type Description accountId string Unique account ID (generated by TG) for
every account that is linked. accountHolderName string Comma separated list of
full names of the account holder. In case of a joint account, it will include
all account holder names. nickname string Nickname.
LIST ACCOUNT TRANSACTIONS
GET /accountInformation/v1/accounts/{accountId}/transactions enables you to
fetch transactions for a given account ID by providing the required parameters
listed below.
Works with - Coming Soon
REQUEST HEADER
Header Key Header Value Notes Content-Type application/json Authorization Bearer
<your_access_token> Token will contain the user identifier
Note: In addition to the above, also include other headers as documented in
Request Headers section
REQUEST URL
GET /accountInformation/v1/accounts/{accountId}/transactions
REQUEST PARAMETERS
Parameter Name Type Description page Integer
optional Desired results page number (defaults to 1). fromBookingDateTime string
optional Start timestamp for transaction request in DateTime format.
toBookingDateTime string
optional End timestamp for transaction request in DateTime format.
REQUEST PATH PARAMETERS
Path Parameter Name Type Description accountId string
required TG account ID to request transactions for.
> Sample Request
Copy to Clipboardcurl --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'
Copy to Clipboardurl = "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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar 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)
Copy to Clipboard{
"transactions": [
{
"transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"providerId": "NBOB",
"transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
"category": {
"group": "Expense",
"name": "Entertainment & Leisure"
},
"merchant": {
"name": "NETFLIX.COM"
},
"creditDebitIndicator": "DEBIT",
"amount": {
"value": 14.99,
"currency": "BHD"
},
"bookingDateTime": "2021-12-22T01:59:30.208+00:00"
}
],
"meta": {
"totalCountOfRecords": 100,
"totalCountOfPages": 10,
"pageNumber": 4,
"pageSize": 10
},
"links": [
{
"rel": "FIRST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=1"
},
{
"rel": "PREVIOUS",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=3"
},
{
"rel": "NEXT",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=5"
},
{
"rel": "LAST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/transactions?page=10"
}
]
}
Note: In the sample response JSON, the pagination Meta object indicates that
there are 10 records per page (pageSize), however we have only shown one
transaction here in order to keep this example response as succinct as possible.
Field Type Description transactions Object[] Array of transaction objects for a
given account. transactionId string Unique transaction ID (generated by TG)
for every transaction. accountId string Account ID that the transaction is
linked to (provided as path parameter). providerId string Unique identifier to
represent a provider/bank. transactionDescription string Description of the
transaction provided by the bank. category Object Internally generated
category object for the transaction. group string Top level category group.
enum: Category Group name string Main category name.
enum: Categories merchant Object
nullable Internally generated merchant object for the transaction. name
string Name of the merchant in the transaction. creditDebitIndicator string
Indicates whether the transaction is a credit or debit, e.g. CREDIT, DEBIT.
amount Money Transaction amount. bookingDateTime string Timestamp of when
the transaction was booked in DateTime format. meta Object[] Pagination and
query metadata object. fromBookingDateTime string Start timestamp for
transaction request in DateTime format. toBookingDateTime string End timestamp
for transactions request in DateTime format. totalCountOfRecords Integer Total
count of records. totalCountOfPages Integer Total count of pages for the given
page size. pageNumber Integer Current page number. pageSize Integer Number
of records returned per page. links Link[] Array of Link objects for pagination,
e.g. FIRST, LAST, PREVIOUS, NEXT.
CATEGORY GROUP
Group Definition Income Payments made into account from other financial entities
relating to employment, investments, support from the state, or any other income
source. Expense Payments made from account towards goods and services. Other
Other transactions that do not fall into income or expense groups Uncategorised
Transactions that our service is not able to assign a category to
CATEGORY NAME
Group Name Definition Income Salary & Wages Payment from an employer Interest
Account interest accumulation Profit Profit paid by the bank for customer
deposits Benefits Financial help payment from government, or charitable
organisations Retirement & Pensions Payment towards retirement from government
or private institution Reimbursements & Refunds Reimbursements relating to
merchants, tax, insurance claims Deposits Money deposits; e.g. ATM, cheque,
online Investment Income Earnings from investment vehicles; e.g. cryptocurrency
exchanges, stock-trading applications Other Income All other payments that
represent income Expense Transport Payment towards transportation or travel.
Includes automotive expenses. Entertainment & Leisure Payment towards
entertainment purposes; e.g. events, online content, entertainment venues,
games, tourism Personal Care & Wellbeing Payment towards personal care; e.g.
cosmetics, wellness or fitness providers; e.g. gym Healthcare & Medical Payment
towards healthcare and medical providers Education Payment towards educational
institution or material Childcare Payment towards childcare; e.g. nurseries,
schooling Pets Payment towards pet supplies and care Charity & Donations Payment
towards charity purposes Construction & Trades Payment towards construction,
home improvements, building materials, and tradesmen Currency Exchange &
Remittance Payment towards money service providers; e.g. currency exchange,
international remittance Rent Payment towards rental of home or commercial
properties Hotels & Lodging Payment towards short-term accommodation Business &
Personal Services Payment towards professional service providers with
specialised skills, tools or licenses; e.g. legal, accounting, tailors, laundry,
logistics Insurance Payment towards insurance provider; e.g. health, life
insurance Groceries Payment towards merchant selling foodstuff and perishable
household supplies; e.g. supermarket, convenience store Shopping Payment towards
general merchandise, electronics, fashion, e-commerce Fees & Charges Payment
towards financial institution or government; e.g. late bank payment charges,
overdraft, municipality fees Bills & Utilities Payment towards essential
services; e.g. phone, broadband, water, energy Loans & Mortgages Payment towards
loan or mortgage repayment Eating Out Payment towards dining; includes
restaurants, venues that serve food & drink Taxes Tax payment Cash Withdrawals
Cash withdrawals from ATMs or CDMs Islamic Financing Payment towards
Shari'a-compliant financing contracts; e.g. Murabaha Other Expenses Expense not
aligned to other existing category Other Transfers Money transfers from/to other
bank accounts Credit Card Payments Payment towards credit card repayment
Investment Payments Payment towards investment vehicles; e.g. cryptocurrency
exchanges, stock-trading applications Savings Money transfer to savings account
Other Transactions Other transactions not aligned to other existing category
Uncategorised Uncategorised Transactions which we have not been able to
categorise
ERRORS
No endpoint specific errors. Generic errors will carry details around any bad
input parameters passed.
Note: This section list out summary of specific errors for this API. Refer here
for generic errors and more detailed explanation.
Note: The category names will evolve over time and it is recommended to practice
defensive coding when using category names.
LIST ACCOUNT RAW TRANSACTIONS
Note: Coming soon
GET /accountInformation/v1/accounts/{accountId}/rawtransactions enables you to
fetch transactions for a given account ID that have not been enriched by
providing the required parameters listed below.
Works with - Coming Soon
REQUEST HEADER
Header Key Header Value Notes Content-Type application/json Authorization Bearer
<your_access_token> Token will contain the user identifier
Note: In addition to the above, also include other headers as documented in
Request Headers section
REQUEST URL
GET /accountInformation/v1/accounts/{accountId}/rawtransactions
REQUEST PARAMETERS
Parameter Name Type Description page Integer
optional Desired results page number (defaults to 1). fromBookingDateTime string
optional Start timestamp for transaction request in DateTime format.
toBookingDateTime string
optional End timestamp for transaction request in DateTime format.
REQUEST PATH PARAMETERS
Path Parameter Name Type Description accountId string
required TG account ID to request transactions for.
> Sample Request
Copy to Clipboardcurl --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'
Copy to Clipboardurl = "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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar 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)
Copy to Clipboard{
"transactions": [
{
"transactionId": "65a1f9a3-2b0d-4d76-07bb-99badfb6933a",
"accountId": "85a2c9f4-7a9d-4c66-97da-83babfb8832a",
"providerId": "NBOB",
"transactionDescription": "FDR-POS-APR18 USD14.99 Netflix.com",
"creditDebitIndicator": "DEBIT",
"amount": {
"value": 14.99,
"currency": "BHD"
},
"bookingDateTime": "2021-12-22T01:59:30.208+00:00"
}
],
"meta": {
"totalCountOfRecords": 100,
"totalCountOfPages": 10,
"pageNumber": 4,
"pageSize": 10
},
"links": [
{
"rel": "FIRST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=1"
},
{
"rel": "PREVIOUS",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=3"
},
{
"rel": "NEXT",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=5"
},
{
"rel": "LAST",
"href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/85a2c9f4-7a9d-4c66-97da-83babfb8832a/rawtransactions?page=10"
}
]
}
Note: In the sample response JSON, the pagination Meta object indicates that
there are 10 records per page (pageSize), however we have only shown one
transaction here in order to keep this example response as succinct as possible.
Field Type Description transactions Object[] Array of transaction objects for a
given account. transactionId string Unique transaction ID (generated by TG)
for every transaction. accountId string Account ID that the transaction is
linked to (provided as path parameter). providerId string Unique identifier to
represent a provider/bank. transactionDescription string Description of the
transaction provided by the bank. creditDebitIndicator string Indicates
whether the transaction is a credit or debit, e.g. CREDIT, DEBIT. amount Money
Transaction amount. bookingDateTime string Timestamp of when the transaction
was booked in DateTime format. meta Object[] Pagination and query metadata
object. fromBookingDateTime string Start timestamp for transaction request in
DateTime format. toBookingDateTime string End timestamp for transactions
request in DateTime format. totalCountOfRecords Integer Total count of
records. totalCountOfPages Integer Total count of pages for the given page
size. pageNumber Integer Current page number. pageSize Integer Number of
records returned per page. links Link[] Array of Link objects for pagination,
e.g. FIRST, LAST, PREVIOUS, NEXT.
ERRORS
No endpoint specific errors. Generic errors will carry details around any bad
input parameters passed.
Note: This section list out summary of specific errors for this API. Refer here
for generic errors and more detailed explanation.
INSIGHTS
Note: Coming soon
Accepts a list of raw transactions and returns transactions enriched with
category and merchant.
Supported APIs are given below
Description Endpoint Enrich transactions POST /ingest/v1/enrich Fetch salaries
GET /insights/v1/salary
ENRICH TRANSACTIONS
POST /ingest/v1/enrich enables you to have your users transactions enriched with
merchant and category.
The API should be called from your backend/server and it returns a list of the
requested transactions and enrichment information.
Works with - Coming Soon
REQUEST URL
POST /ingest/v1/enrich
REQUEST HEADERS
Header Key Header Value Notes Authorization Bearer <your_access_token> Token
will contain the enrich: category and enrich: merchant scopes Content-Type
application/json
Note: In addition to the above, also include other headers as documented in
Request Headers section
REQUEST BODY
> Sample Request
Copy to Clipboardcurl --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"
}'
Copy to Clipboardimport 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)
Copy to ClipboardOkHttpClient 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();
Copy to Clipboardvar 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)
Copy to Clipboard[
{
"transactionId": "1",
"categorisation":
{
"group":"Expense",
"category":"Groceries"
},
"merchantName":"KHCB LULU HYPER HIDD",
"transactionType":"merchant"
},
{
"transactionId": "2",
"categorisation":
{
"group":"Expense",
"category":"Groceries"
},
"merchantName":"ALJAZIRA SUPERMARKET",
"transactionType":"merchant"
}
]
Field Type Description transactionId string Unique identifier of the
transaction. categorisation Object Categorisation information of the
transaction. group string Categorisation group of the transaction. category
string Categorisation category of the transaction. merchantName string Merchant
name for the transaction. transactionType string Type of transaction.
AVAILABLE PROVIDERS
The table below details available providers by ID and name.
Provider ID Provider Name ABIB Al Baraka Islamic Bank ALSA Al Salam Bank BBKU
Bank of Bahrain and Kuwait BIBB Bahrain Islamic Bank BLUE Blue Bank * ESKB Eskan
Bank ABCO Arab Banking Corporation FIBH Ithmaar Bank KFHO Kuwait Finance House
(Bahrain) KHCB Khaleeji Commercial Bank NBOB National Bank of Bahrain NBOK
National Bank of Kuwait SCBL Standard Chartered Bank
*Blue Bank is a demo provider only available in Sandbox.
FETCH SALARIES
GET /insights/v1/salary enables you to fetch salaries for a given user, for the
last 3 months.
This API should be called from your backend/server and it returns a list of
salary amounts with bookingDateTime and month.
Works with - insights.salary:list
REQUEST URL
GET /insights/v1/salary
REQUEST HEADERS
Header Key Header Value Notes Authorization Bearer <your_access_token> Token
will contain the insights.salary:list scope
Note: In addition to the above, also include other headers as documented in
Request Headers section
> Sample Request
Copy to Clipboardcurl --location --request GET 'https://api.sandbox.tarabutgateway.io/insights/v1/salary' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {valid-tg-token}'
Copy to Clipboardimport requests
import json
url = "https://api.sandbox.tarabutgateway.io/insights/v1/salary"
headers = {
'Authorization': 'Bearer <your_access_token>',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers)
Copy to ClipboardOkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
.url("https://api.sandbox.tarabutgateway.io/insights/v1/salary")
.method("GET")
.addHeader("Authorization", "Bearer <your_access_token>")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
Copy to Clipboardvar client = new RestClient("https://api.sandbox.tarabutgateway.io/insights/v1/salary");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <your_access_token>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
RESPONSE FIELDS
> Sample Response (200 Success)
Copy to Clipboard{
"salaries" : [
{
"salaryAmount": {
"value": "400.0",
"currency":"BHD"
},
"bookingDateTime": "2022-10-01T00:00:00.000Z",
"monthIndicator": 10
},
{
"salaryAmount": {
"value": "405.0",
"currency":"BHD"
},
"bookingDateTime": "2022-09-01T00:00:00.000Z",
"monthIndicator": 9
},
{
"salaryAmount": {
"value": "410.0",
"currency":"BHD"
},
"bookingDateTime": "2022-08-01T00:00:00.000Z",
"monthIndicator": 8
}
]
}
Field Type Description salaries Object[] Array of Salary objects for a given
user. salaryAmount Money Salary amount. bookingDateTime string Timestamp of
when the transaction was booked in DateTime format. monthIndicator Integer
Month of salary credit. The value for this field starts from 1(1 = January).
ERROR HANDLING & SCHEMA
A detailed list of all the errors thrown by TG APIs. Please refer Error Response
in the overview section to understand generic error schema.
GENERIC ERRORS
Copy to ClipboardHttp Status Code: 400
{
"error":"INVALID_FIELDS",
"errorMessage":"Required fields missing or invalid field or field values sent in the request",
"details":[
{
"fieldName":"paymentAmount.value",
"message":"must not be null"
}
],
"traceId":"233333"
}
These are common errors that can be thrown for any API endpoint.
HTTP Code error Description 500 INTERNAL_SERVER_ERROR Returned when an
unexpected error as occurred on TG's end. 503 PLANNED_MAINTENANCE Returned when
the services are unavailable due to a planned maintenance. If you are not
informed prior about the maintenance, please reach out to TG support team. 403
API_ACCESS_DENIED Access Token used for this API call is not issued with
required scope for this API call. Please check your scope configured or
requested for the access token. 401 UNAUTHORIZED_ACCESS Access token used is
invalid or expired. Regenerate the access token. 400 INVALID_REQUEST Body could
not be parsed or invalid content type passed mis-matched. Review your request
body & header. 400 INVALID_FIELDS Required fields missing or invalid field or
field values sent in the request; This error will also return details object
providing details around specific field. Review the input request parameters.
400 INVALID_HEADERS Required header field is missing or invalid in the request;
This error will also return details object providing details around specific
header field. Review the header parameters 404 API_NOT_FOUND End point does not
exist. Re-verify your end point or API url and path parameters.
Note: API Specific errors are documented along with respective end points above.
ENTERPRISE SERVICES
Tarabut Gateway offers premium features, endpoints and capabilities, some of
which are listed below that enable deeper custom integrations. Get in touch to
partner with us to power your products and services.
WEBHOOKS
We allow subscription to multiple URLs to drive a specific web hook event. Once
subscribed, your URL will begin recieving events (e.g. new transactions
available, balance changes and consents expired) to drive more real time
experiences in your product or service.
SDKS
As an alternative to REST based APIs, TG also provides SDK to make it faster to
build integrations with TG's products. It also removes the hassle of maintaining
those connections yourself and is constantly updated to give end users the best
possible user experience.
PFM FEATURE FUNCTIONALITY
Tarabut Gateway has deep experience of building PFMs for banks and fintechs. We
can provide customers more value with our ready to use solutions – and help end
users better understand their needs – with tools and personalised insights that
help improve their finances. Our PFM end points enable rapid build and delivery
of PFM use cases - to increase engagement, inspire action and boost conversion.
*To learn more about our Enterprise features and how we can partner with you to
power your use case please contact us on developers@tarabutgateway.com. *
CHANGELOG
WHAT'S NEW WITH TG!
The changelog provides a view of any changes or updates made to the TG APIs and
associated products. Keep a track of any enhancements or bug fixes with our
regular updates.
RELEASE ACCOUNT INFORMATION APIS
Account Information Account Information product is launched in Bahrain which
enables users and businesses to request for account and categorised transaction
information from financial institutions upon end-user consent securely.
March 2022
RELEASE PAYMENT INITIATION APIS
Payment Initiation Payment Initiation product is launched in Bahrain which
allows for seamless bank to bank payments for various use cases such as bill
payment, checkout, and account to account payments.
October 2021
cURL java-OkHttp python-Request C#-RestSharp