Tarabut Developer Hub

https://docs.tarabut.com/
Admin
Tarabut Developer Hub provides comprehensive documentation and resources for developers to integrate...
Tokens:230,734
Snippets:435
Trust Score:8.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Account Information Example (JSON)

Source: https://docs.tarabut.com/v1.0/reference/getaccountsv2

An example of account information data in JSON format. This demonstrates the typical structure and values for account ID, holder name, product type, status, currency, dates, consents, links, balance, and metadata.

```json
{
  "accountId": "c0960f92-b2fa-4e34-bc1b-f081b8587e0a",
  "accountHolderName": "Ibrahim Adil",
  "accountProductType": "CurrentAccount",
  "accountDescription": "Ibrahim Adil - CurrentAccount",
  "status": "Active",
  "providerId": "BLUE",
  "accountCurrency": "BHD",
  "accountOpeningDate": "2021-01-11T09:51:21.124677Z",
  "lastUpdatedDateTime": "2025-12-27T20:21:34.487+00:00",
  "consents": [
    {
      "id": "8e44864f-b5f9-4187-951d-a2d7d1d2809e",
      "expiryDate": "2026-01-14T08:51:51.144877Z",
      "status": "ACTIVE"
    },
    {
      "id": "b2682a80-12b6-3f2c-bcde-cf2e832bad31",
      "expiryDate": "2026-09-05T05:45:34.845901Z",
      "status": "ACTIVE"
    }
  ],
  "links": [
    {
      "rel": "TRANSACTIONS",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v2/accounts/c0960f92-b2fa-4e34-bc1b-f081b8587e0a/transactions"
    },
    {
      "rel": "BALANCES",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v2/accounts/c0960f92-b2fa-4e34-bc1b-f081b8587e0a/balances"
    }
  ]
}
```

--------------------------------

### Account with Salary Example

Source: https://docs.tarabut.com/v1.0/reference/getincomeinsightsdetails

An example of an account object that includes salary information and recurring credit summary. This demonstrates how salary-related transactions are structured, including frequency and transaction details.

```json
{
  "accountId": "6af49d8f-54e4-4b0e-b017-10c72f55c6d3",
  "accountCurrency": "BHD",
  "providerId": "BLUE",
  "source": "Bank API",
  "lastUpdated": "2023-10-04T00:00:00.123Z",
  "accountHasSalary": true,
  "startDate": "2023-01-01",
  "endDate": "2024-01-30",
  "recurringCreditSummary": [
    {
      "streamType": "Salary",
      "frequency": "Monthly",
      "count": 2,
      "transactions": [
        {
          "transactionId": "8e3a5f5a-a24a-45a6-ba4c-c28ffff0794c",
          "description": "FAWRI/ /SNDT/CR/00000000/IBAN/ M/S.TARABUT GATEWAY",
          "monthIndicator": "01"
        }
      ]
    }
  ]
}
```

--------------------------------

### Account Transaction Example

Source: https://docs.tarabut.com/v1.0/reference/getincomeinsightsdetails

An example of an account object containing irregular credit summary and associated links. This demonstrates how transaction data is presented, including details like account ID, currency, and a list of transactions.

```json
{
  "accountId": "7eeec027-16d2-41bf-abad-70a81aabb2b3",
  "accountCurrency": "BHD",
  "providerId": "BLUE",
  "source": "Bank API",
  "lastUpdated": "2023-10-04T00:00:00.123Z",
  "accountHasSalary": false,
  "startDate": "2023-01-01",
  "endDate": "2024-01-30",
  "recurringCreditSummary": null,
  "irregularCreditSummary": {
    "totalAmount": "100.00",
    "count": 1,
    "transactions": [
      {
        "transactionId": "9ce720ec-3da5-4a4e-a26d-9b46f5565a16",
        "description": "TFR-Fawri+ Transfer-BP0000000000AAAA BH00AAAA00000000000000 BBKUBHBM",
        "monthIndicator": "01",
        "amount": "100.00",
        "date": "2024-01-01T00:00:00.000Z"
      }
    ]
  },
  "links": [
    {
      "ref": "TRANSACTIONS",
      "href": "https://api.sandbox.tarabutgateway.io/accountInformation/v1/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?fromBookingDateTime=2023-12-01T00:00:00.000Z&toBookingDateTime=2024-01-01T00:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Income Insight Result Example (JSON)

Source: https://docs.tarabut.com/v1.0/reference/getincomeinsightssalary

Provides a concrete example of an income insight result object. This demonstrates the expected data format for account details, date ranges, and salary transaction summaries.

```json
[
  {
    "accountId": "7eeec027-16d2-41bf-abad-70a81aabb2b3",
    "accountCurrency": "BHD",
    "providerId": "BLUE",
    "source": "Bank API",
    "lastUpdated": "2024-11-04T00:00:00.123Z",
    "accountHasSalary": true,
    "startDate": "2024-09-01",
    "endDate": "2024-11-30",
    "salarySummary": [
      {
        "streamType": "Salary",
        "frequency": "Monthly",
        "count": 2,
        "transactions": [
          {
            "transactionId": "8e3a5f5a-a24a-45a6-ba4c-c28ffff0794c",
            "description": "PAYROLL/ JAN salary 2024 ABC company",
            "monthIndicator": "10",
            "amount": "1400.00",
            "date": "2024-10-27T08:31:02.907Z"
          },
          {
            "transactionId": "55090e5d-17a5-4555-8fe9-4a6713101bec",
            "description": "PAYROLL/ FEB salary 2024 ABC company",
            "monthIndicator": "11",
            "amount": "1400.00",
            "date": "2024-11-27T08:31:02.907Z"
          }
        ]
      }
    ]
  }
]
```

--------------------------------

### Example Account Information with Irregular Credits (JSON)

Source: https://docs.tarabut.com/reference/getincomeinsightsdetails

An example JSON payload representing account information that includes irregular credit transactions. It shows details like account ID, currency, provider, and a list of irregular transactions with their respective amounts and dates.

```json
{
  "accountId": "7eeec027-16d2-41bf-abad-70a81aabb2b3",
  "accountCurrency": "SAR",
  "providerId": "BLUE",
  "source": "Bank API",
  "lastUpdated": "2023-10-04T00:00:00.123Z",
  "accountHasSalary": false,
  "startDate": "2023-01-01",
  "endDate": "2024-01-30",
  "recurringCreditSummary": null,
  "irregularCreditSummary": {
    "totalAmount": "100.00",
    "count": 1,
    "transactions": [
      {
        "transactionId": "9ce720ec-3da5-4a4e-a26d-9b46f5565a16",
        "description": "عادلTime:16:00:00**Note:W-/FRACCT/29700608017169991FR",
        "monthIndicator": "01",
        "amount": "1000.00",
        "date": "2024-01-01T00:00:00.000Z"
      }
    ]
  },
  "links": [
    {
      "ref": "TRANSACTIONS",
      "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?fromBookingDateTime=2023-12-01T00:00:00.000Z&toBookingDateTime=2024-01-01T00:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Transaction Response Metadata Example

Source: https://docs.tarabut.com/v1.0/reference/gettransactionsv2

Provides an example of the metadata returned with a transaction request response. This includes the total number of records, total pages, current page number, page size, and the date-time range for the transactions included.

```json
{
  "meta": {
    "totalCountOfRecords": 2,
    "totalCountOfPages": 1,
    "pageNumber": 1,
    "pageSize": 10,
    "fromBookingDateTime": "2023-01-01T15:34:12Z",
    "toBookingDateTime": "2023-08-27T15:34:12Z",
    "lastTransactionsUpdateDatetime": "2024-01-30T10:10:28.069387Z"
  }
}
```

--------------------------------

### Example Account Information with Recurring Salary (JSON)

Source: https://docs.tarabut.com/reference/getincomeinsightsdetails

An example JSON payload illustrating account information that includes a recurring salary credit. It details the salary stream type, monthly frequency, count, and associated transactions, alongside account-level information.

```json
{
  "accountId": "6af49d8f-54e4-4b0e-b017-10c72f55c6d3",
  "accountCurrency": "SAR",
  "providerId": "BLUE",
  "source": "Bank API",
  "lastUpdated": "2023-10-04T00:00:00.123Z",
  "accountHasSalary": true,
  "startDate": "2023-01-01",
  "endDate": "2024-01-30",
  "recurringCreditSummary": [
    {
      "streamType": "Salary",
      "frequency": "Monthly",
      "count": 2,
      "transactions": [
        {
          "transactionId": "8e3a5f5a-a24a-45a6-ba4c-c28ffff0794c",
          "description": "PAYROLL/ JAN salary 2024 ABC company",
          "monthIndicator": "01"
        }
      ]
    }
  ],
  "irregularCreditSummary": null,
  "links": []
}
```

--------------------------------

### Create Customer Intent Response JSON

Source: https://docs.tarabut.com/docs/create-intent

A successful response from the Create Intent API includes a connectUrl to initiate the user consent journey, an intentId for tracking, and an expiry timestamp. The connectUrl should be used to guide the end-user.

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

--------------------------------

### Get All Consents API Response (JSON)

Source: https://docs.tarabut.com/docs/handling-multiple-use-cases

Example response from the Get All Consents endpoint, detailing customer consent information. Each consent object includes an ID, status, expiry date, start date, purpose statement, product, and provider ID. This data helps in understanding customer preferences for various use cases.

```json
[
	{
		"id": "dea58319-8ad8-4c7c-9f88-3d0511c05550",
		"status": "ACTIVE",
		"expiryDate": "2026-08-24T08:58:31Z",
		"startDate": "2025-08-24T11:58:31.440Z",
		"purposeStatement": "ACCOUNT_AGGREGATION",
		"product": "BANK_ACCOUNTS_AGGREGATION",
		"providerId": "BLUE"
	},
	{
		"id": "8446bb01-6494-404a-ab3a-0f51a8085554",
		"status": "ACTIVE",
		"expiryDate": "2026-08-26T12:12:35Z",
		"startDate": "2025-08-26T15:12:37.206Z",
		"purposeStatement": "CREDIT_ASSESSMENT",
		"product": "CREDIT_LIMIT_INCREASE",
		"providerId": "BLUE"
	}
]
```

--------------------------------

### Retrieve Payment Status (HTTP GET)

Source: https://docs.tarabut.com/v1.0/docs/single-payment-status-updates

This example shows how to retrieve the status of a specific payment using an HTTP GET request. It requires the relevant base URL and an Authorization header containing a payment token. This allows merchants to actively poll for payment status updates.

```http
GET /api/v1/payments/ HTTP/1.1
Host: <relevant_base_url>
Authorization: Bearer <payment_token>
```

--------------------------------

### Account Information Example Response

Source: https://docs.tarabut.com/reference/getincomeinsights

Provides a concrete example of the JSON response structure for account information. This includes details on account ID, currency, source, last updated timestamp, salary indicator, date range, and summaries for recurring and irregular credits.

```json
[
  {
    "accountId": "7eeec027-16d2-41bf-abad-70a81aabb2b3",
    "accountCurrency": "SAR",
    "source": "Bank API",
    "lastUpdated": "2023-10-04T00:00:00.123Z",
    "accountHasSalary": true,
    "startDate": "2023-01-01",
    "endDate": "2023-09-30",
    "recurringCreditSummary": [
      {
        "streamDescriptionPattern": "Monthly Salary from ABC Corp",
        "streamType": "Salary",
        "frequency": "Monthly",
        "avgAmount": "25000.00",
        "links": [
          {
            "ref": "TRANSACTIONS",
            "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?fromBookingDateTime=2023-12-01T00:00:00.000Z&toBookingDateTime=2024-03-01T00:00:00.000Z"
          }
        ]
      },
      {
        "streamDescriptionPattern": "Rental Income from Property XYZ",
        "streamType": "Others",
        "frequency": "Monthly",
        "avgAmount": "12000.00",
        "links": [
          {
            "ref": "TRANSACTIONS",
            "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?fromBookingDateTime=2023-12-01T00:00:00.000Z&toBookingDateTime=2024-03-01T00:00:00.000Z"
          }
        ]
      }
    ],
    "irregularCreditSummary": {
      "totalAmount": "100.00",
      "avgAmount": "10.00",
      "links": [
        {
          "ref": "TRANSACTIONS",
          "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v1/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?fromBookingDateTime=2023-12-01T00:00:00.000Z&toBookingDateTime=2024-03-01T00:00:00.000Z"
        }
      ]
    }
  }
]
```

--------------------------------

### List All Consents Example Response (JSON)

Source: https://docs.tarabut.com/docs/build-your-own-consent-management-dashboard

This JSON structure represents the response when retrieving all consents for a customer. It includes the consent ID, status, expiry date, start date, and provider ID for each consent.

```json
[
  {
    "id": "b2682a80-12b6-3f2c-bcde-cf2e832bad31",
    "status": "ACTIVE",
    "expiryDate": "2024-09-05T05:45:34.845Z",
    "startDate": "2023-09-06T05:45:35.332Z",
    "providerId": "BLUE"
  },
  {
    "id": "7410305e-04d5-3bc3-b2ca-557b73cf5e88",
    "status": "EXPIRED",
    "expiryDate": "2024-05-23T11:22:01.745Z",
    "startDate": "2023-05-24T11:22:04.100Z",
    "providerId": "BLUE"
  },
  {
    "id": "a6ea99b1-bbf7-3c72-97c9-864cae2d93b7",
    "status": "REVOKED",
    "expiryDate": "2024-04-26T12:31:47.109Z",
    "revokeDate": "2023-04-29T12:31:47.109Z",
    "startDate": "2023-04-27T12:31:47.109Z",
    "providerId": "BLUE"
  }
]
```

--------------------------------

### Environment URLs

Source: https://docs.tarabut.com/v1.0/docs/environment-urls-1

Tarabut provides two environments: production for live transactions and sandbox for testing and UAT. Always use HTTPS for API interactions.

```APIDOC
## Environment URLs

Tarabut offers two environments for API interactions:

### Production Environment
- **Base URL**: `https://payments.tarabutgateway.io/`
- **Description**: Use this environment for live payment processing.

### Sandbox (UAT) Environment
- **Base URL**: `https://sandbox.payments.tarabutgateway.io/`
- **Description**: Use this environment for testing, development, and User Acceptance Testing (UAT).

**Note**: Always use HTTPS for all API communications.
```

--------------------------------

### Create Customer Intent API

Source: https://docs.tarabut.com/docs/create-intent

Use the Create Intent API to allow your customers to initiate the account linking process by creating an intent.

```APIDOC
## POST /v2/intents

### Description
This endpoint allows customers to initiate the account linking process by creating an intent. A unique customer identifier must be provided.

### Method
POST

### Endpoint
/v2/intents

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **user** (object) - Required - User information.
  - **customerUserId** (string) - Required - A unique identifier for the customer. It is recommended not to pass any PII.
  - **firstName** (string) - Optional - The first name of the customer.
  - **lastName** (string) - Optional - The last name of the customer.
  - **email** (string) - Optional - The email address of the customer.
- **providerType** (string) - Required - The type of provider (e.g., "Retail").
- **language** (string) - Required - The language code for the intent (e.g., "EN").
- **redirectUrl** (string) - Required - One of the pre-configured redirect URLs in the Tarabut Dev Portal.

### Request Example
```json
{
	"user": {
		"customerUserId": "38737982364",
		"firstName": "John",
		"lastName": "Snow",
		"email": "some@email.com"
	},
  "providerType": "Retail",
	"language": "EN",
	"redirectUrl": "http://myredirectURL.me"
}
```

### Response
#### Success Response (200)
- **connectUrl** (string) - The URL to initiate the consent journey.
- **intentId** (string) - The unique identifier for the intent.
- **expiry** (string) - The expiration date and time of the intent.

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

> Note
> This API should be called from your backend/server. The Connect URL starts the consent journey for an end-user. An intent is not complete until the user authorizes consent at the bank.
```

--------------------------------

### View Last Account Update Time (JSON Response)

Source: https://docs.tarabut.com/v1.0/docs/retrieve-account-transaction-data

This JSON example illustrates a response from the Get Accounts API. The `lastUpdatedDateTime` field within each account object indicates when that specific account's data was last updated. This format is standard JSON and does not require a specific programming language for interpretation.

```json
{
  "accounts": [
    {
      "accountId": "c0960f92-b2fa-4e34-bc1b-f081b8587e0a",
      "accountHolderName": "Ibrahim Adil",
      "accountProductType": "CreditCard",
      "accountDescription": "Ibrahim Adil - SAR Credit Card (thin file)",
      "providerId": "BLUE",
      "consents": [
        {
          "id": "8e44864f-b5f9-4187-951d-a2d7d1d2809e",
          "expiryDate": "2025-01-14T08:51:51.144Z",
          "status": "ACTIVE"
        }
      ],
      "lastUpdatedDateTime": "2023-09-27T20:21:34.487Z",
      "links": [
        {
          "rel": "TRANSACTIONS",
          "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v2/accounts/c0960f92-b2fa-4e34-bc1b-f081b8587e0a/transactions"
        },
        {
          "rel": "BALANCES",
          "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v2/accounts/c0960f92-b2fa-4e34-bc1b-f081b8587e0a/balances"
        }
      ],
      "identifiers": {
        "type": "maskedPAN",
        "value": "******************6494"
      }
    }
  ]
}
```

--------------------------------

### Authentication and Token Generation

Source: https://docs.tarabut.com/reference/createaccesstokenv2

This section details the process of obtaining an access token, including request parameters and response structures for both success and error scenarios.

```APIDOC
## POST /oauth/token

### Description
Obtains an access token for authenticating API requests. Requires client credentials and optionally a grant type.

### Method
POST

### Endpoint
/oauth/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Optional - Specifies the grant type for authentication (e.g., "client_credentials").

#### Request Body
- **clientId** (string) - Required - Your application's client ID.
- **clientSecret** (string) - Required - Your application's client secret.

### Request Example
```json
{
  "clientId": "your_client_id",
  "clientSecret": "your_client_secret",
  "grant_type": "client_credentials"
}
```

### Response
#### Success Response (200)
- **accessToken** (string) - The generated access token.
- **expiresIn** (integer) - Validity of your access token in seconds.
- **tokenType** (string) - Type of the generated access token (e.g., "Bearer").

#### Response Example
```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900,
  "tokenType": "Bearer"
}
```

#### Error Response (400)
- **error** (string) - Error name (e.g., "INVALID_FIELDS").
- **errorMessage** (string) - Error message describing the issue.
- **traceId** (string) - Tracing ID for support.
- **details** (array) - Array of specific field errors.
  - **fieldName** (string) - Field with invalid input.
  - **message** (string) - Error message for the invalid input.

#### Error Response Example (400)
```json
{
  "error": "INVALID_FIELDS",
  "errorMessage": "Required fields missing or invalid field or field values sent in the request",
  "traceId": "35278ec975f69298",
  "details": [
    {
      "fieldName": "clientId",
      "message": "must not be empty"
    }
  ]
}
```

#### Error Response (500)
- **error** (string) - Error name (e.g., "INTERNAL_SERVER_ERROR").
- **errorMessage** (string) - Error message indicating an internal server issue.
- **traceId** (string) - Tracing ID for support.

#### Error Response Example (500)
```json
{
  "error": "INTERNAL_SERVER_ERROR",
  "errorMessage": "An unexpected error occured, please reach out to support",
  "traceId": "c5eb65e2e41ada50"
}
```
```

--------------------------------

### View Last Transaction Update Time (JSON Response)

Source: https://docs.tarabut.com/v1.0/docs/retrieve-account-transaction-data

This JSON structure shows an example response from the Get Account Transactions API, highlighting the `lastTransactionsUpdateDatetime` field within the `meta` object. This field indicates when the transaction data was last synchronized. No specific programming language is required to view this data structure.

```json
{
  "transactions": [
    {
      "transactionId": "8bacc675-3141-4790-a0c5-59d9b54c8c5e",
      "accountId": "7eeec027-16d2-41bf-abad-70a81aabb2b3",
      "providerId": "BLUE",
      "transactionDescription": "FDR-NOV09 BAHRAIN DUTY FREE CO WLL-048",
      "category": {
        "group": "Expense",
        "name": "Shopping",
        "icon": "https://tg-merchants-prod.s3.me-south-1.amazonaws.com/category/EXPENSE_SHOPPING.svg"
      },
      "merchant": {
        "name": "BAHRAIN DUTY FREE",
        "logo": "https://tg-merchants-prod.s3.me-south-1.amazonaws.com/merchant/fc66f571e47e0ce838d3cfd33a14cf11.png",
        "merchantCategoryCode": ""
      },
      "creditDebitIndicator": "Debit",
      "amount": {
        "value": 14.96,
        "currency": "BHD"
      },
      "bookingDateTime": "2023-10-17T00:00:00.000Z"
    }
  ],
  "meta": {
    "totalCountOfRecords": 1,
    "totalCountOfPages": 1,
    "pageNumber": 1,
    "pageSize": 10,
    "lastTransactionsUpdateDatetime": "2024-01-30T10:10:28.069Z"
  },
  "links": [
    {
      "rel": "FIRST",
      "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v2/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?page=1&fromBookingDateTime=2023-01-01T15:34:12Z&toBookingDateTime=2023-08-27T15:34:12Z"
    },
    {
      "rel": "PREVIOUS",
      "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v2/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?page=1&fromBookingDateTime=2023-01-01T15:34:12Z&toBookingDateTime=2023-08-27T15:34:12Z"
    },
    {
      "rel": "NEXT",
      "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v2/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?page=1&fromBookingDateTime=2023-01-01T15:34:12Z&toBookingDateTime=2023-08-27T15:34:12Z"
    },
    {
      "rel": "LAST",
      "href": "https://api.sau.sandbox.tarabutgateway.io/accountInformation/v2/accounts/7eeec027-16d2-41bf-abad-70a81aabb2b3/transactions?page=1&fromBookingDateTime=2023-01-01T15:34:12Z&toBookingDateTime=2023-08-27T15:34:12Z"
    }
  ]
}
```

--------------------------------

### Display Consent Details (JSON Response)

Source: https://docs.tarabut.com/v1.0/docs/build-your-own-consent-management-dashboard

Displays the detailed information for a specific consent. This is the response format obtained after successfully calling the 'Get Consent Details' API endpoint. It includes consent ID, status, expiry and start dates, provider ID, and connected account details.

```json
{
  "id": "b2682a80-12b6-3f2c-bcde-cf2e832bad31",
  "status": "ACTIVE",
  "expiryDate": "2024-09-05T05:45:34.845Z",
  "startDate": "2023-09-06T05:45:35.332Z",
  "providerId": "BLUE",
  "connectedAccounts": [
    {
      "id": "baa09901-e314-4813-aa64-2a5ffe33ce10",
      "accountProductType": "CurrentAccount",
      "identifiers": [
        {
          "type": "IBAN",
          "value": "BH6530400108071059170014"
        }
      ]
    },
    {
      "id": "413c4a4a-4f70-4a62-b683-3eb31bed5474",
      "accountProductType": "CreditCard",
      "identifiers": [
        {
          "type": "maskedPAN",
          "value": "******************4942"
        }
      ]
    },
    {
      "id": "15136947-b730-4ffa-88b7-ad696b4c19b0",
      "accountProductType": "CreditCard",
      "identifiers": [
        {
          "type": "maskedPAN",
          "value": "******************4701"
        }
      ]
    }
  ]
}
```

--------------------------------

### API Endpoint Construction

Source: https://docs.tarabut.com/v1.0/docs/environment-urls-1

Learn how to construct full API URLs by combining the appropriate base URL with specific API endpoints. An example is provided for creating a PIR construct.

```APIDOC
## API Endpoint Construction

To access Tarabut APIs, you need to combine the environment-specific **Base URL** with the desired **API endpoint**.

### Example: Creating a PIR

To create a PIR (Payment Initiation Request), you would construct the URL as follows:

`Base URL` + `/api/v1/payments/`

For instance, using the sandbox environment:

`<https://sandbox.payments.tarabutgateway.io/api/>v1/payments/`

**General Format**: `[Base URL]/api/v1/[resource]/`
```

--------------------------------

### Example Account Balance Payload

Source: https://docs.tarabut.com/reference/getbalancehistory

Provides a sample JSON payload demonstrating the structure and typical values for account balance information, including historical data.

```json
{
  "accountId": "7eeec027-16d2-41bf-abad-70a81aabb2b3",
  "accountCurrency": "SAR",
  "startDate": "2024-06-01T00:00:00",
  "endDate": "2025-06-24T09:53:18.551011624",
  "timeSteps": "1 month",
  "providerId": "BLUE",
  "accountProductType": "CurrentAccount",
  "accountOpeningDate": "2021-01-11T09:51:21.124Z",
  "balanceType": "ClosingAvailable",
  "avgBalanceAmount": "1115.750",
  "balanceHistory": [
    {
      "date": "2025-05-31",
      "amount": 123
    },
    {
      "date": "2025-04-30",
      "amount": 121
    },
    {
      "date": "2025-03-31",
      "amount": 140
    },
    {
      "date": "2025-02-28",
      "amount": 210
    },
    {
      "date": "2025-01-31",
      "amount": 1456
    },
    {
      "date": "2024-12-31",
      "amount": 1056
    },
    {
      "date": "2024-11-30",
      "amount": 2356
    },
    {
      "date": "2024-10-31",
      "amount": 1451
    },
    {
      "date": "2024-09-30",
      "amount": 3455
    },
    {
      "date": "2024-08-31",
      "amount": 1454
    },
    {
      "date": "2024-07-31",
      "amount": 1467
    },
    {
      "date": "2024-06-31",
      "amount": 1554
    }
  ]
}
```

--------------------------------

### Generate Payment Token using cURL

Source: https://docs.tarabut.com/v1.0/docs/getting-started-with-payments

This snippet demonstrates how to generate a payment token by making an HTTP POST request to the Tarabut API using cURL. It requires a client ID and client secret obtained from the Merchant or Partner portal. The generated token is valid for 60 minutes and is used for subsequent API interactions.

```curl
curl --location --request POST 'https://sandbox.payments.tarabutgateway.io/api/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<payment_key>' \
--data-urlencode 'client_secret=<payment_secret>’
```

--------------------------------

### Create Single Domestic Payment Request (Node.js)

Source: https://docs.tarabut.com/v1.0/reference/merchant-single-payments

Example of initiating a single domestic payment request using Node.js. This snippet shows how to make a POST request to the Tarabut Gateway API endpoint using the 'axios' library, sending the necessary JSON payload and headers. Ensure 'axios' is installed.

```javascript
const axios = require('axios');

const createPaymentRequest = async (currency, expirationValue, expirationUnit) => {
  const url = 'https://sandbox.payments.tarabutgateway.io/api/v1/payments';
  const headers = {
    'accept': 'application/json',
    'content-type': 'application/json',
    'Idempotency-Key': 'your-unique-idempotency-key',
    'Authorization': 'Bearer your-access-token'
  };
  const data = {
    currency: currency,
    expiration: {
      unit: expirationUnit,
      value: expirationValue
    }
  };

  try {
    const response = await axios.post(url, data, { headers });
    console.log('Payment request created:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error creating payment request:', error.response ? error.response.data : error.message);
    throw error;
  }
};

// Example usage:
// createPaymentRequest('BHD', 30, 'MINUTES');
```

--------------------------------

### Create Intent API Request | cURL Example

Source: https://docs.tarabut.com/docs/build-your-own-bank-selection-page

Example cURL command to call the Create Intent API. This request requires an access token and a JSON payload containing user details, consent provider ID, and a redirect URL. It initiates the bank connection process.

```curl
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": "BLUE"
  },
    "redirectUrl": "http://override.me/notDefault"
}'
```

--------------------------------

### Create Single Domestic Payment Request (Python)

Source: https://docs.tarabut.com/v1.0/reference/merchant-single-payments

Example of initiating a single domestic payment request using Python. This code snippet utilizes the 'requests' library to send a POST request to the Tarabut Gateway API. It includes the required headers and a JSON payload for the payment details. Ensure 'requests' is installed.

```python
import requests
import json

def create_payment_request(currency, expiration_value, expiration_unit):
    url = 'https://sandbox.payments.tarabutgateway.io/api/v1/payments'
    headers = {
        'accept': 'application/json',
        'content-type': 'application/json',
        'Idempotency-Key': 'your-unique-idempotency-key',
        'Authorization': 'Bearer your-access-token'
    }
    payload = {
        'currency': currency,
        'expiration': {
            'unit': expiration_unit,
            'value': expiration_value
        }
    }

    try:
        response = requests.post(url, headers=headers, data=json.dumps(payload))
        response.raise_for_status()  # Raise an exception for bad status codes
        print('Payment request created:', response.json())
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Error creating payment request: {e}')
        if e.response is not None:
            print('Response data:', e.response.json())
        raise

# Example usage:
# create_payment_request('BHD', 30, 'MINUTES')
```

--------------------------------

### Get Intent API

Source: https://docs.tarabut.com/v1.0/reference/getintent

Enables you to get information about an existing intent using its ID.

```APIDOC
## GET /accountInformation/v1/intent/{intentId}

### Description
Retrieves information about a specific intent using its unique identifier.

### Method
GET

### Endpoint
/accountInformation/v1/intent/{intentId}

### Parameters
#### Path Parameters
- **intentId** (string) - Required - The `intentId` that has been returned from the [Create Intent](https://docs.tarabut.com/v1.0/reference/createintent) endpoint

#### Header Parameters
- **Content-Type** (string) - Required - Specify the body format to JSON format. Default: `application/json`

### Request Example
No request body is required for this GET request.

### Response
#### Success Response (200)
- **intentId** (string) - The intentId.
- **providerId** (string) - The unique identifier of the provider linked to this intentId.
- **intentStatus** (string) - Status of the intent which can be `CREATED`, `INITIATED`,`CONSENT_INITIATED`, `CONSENT_REJECTED`, `CANCELLED_CONSENT_SCREEN`, `COMPLETED`, `EXPIRED`, `CONSENT_REVOKED`, `UNKNOWN`.
- **consentId** (string) - Consent ID generated If the intent status is `COMPLETED`, that can be used for [Consent Management](https://docs.tarabut.com/v1.0/docs/build-your-own-consent-management-dashboard).

#### Response Example
```json
{
  "intentId": "092d24cc-4691-460d-a33b-f54f0b26403c",
  "providerId": "BLUE",
  "intentStatus": "COMPLETED",
  "consentId": "99aa7885-fe3a-4065-9222-c1a0f0917367"
}
```

#### Error Response (401)
- **error** (string) - Error name.
- **errorMessage** (string) - Error message.
- **traceId** (string) - Tracing Id used when you contact support.
- **details** (array) - The array contains details of the error.
  - **fieldName** (string) - Field name that has invalid input.
  - **message** (string) - Error message of the invalid input.

#### Error Response Example (401)
```json
{
  "error": "UNAUTHORIZED_ACCESS",
  "errorMessage": "Not Authenticated",
  "traceId": "278827398026513417",
  "details": [
    {
      "fieldName": "Authorization",
      "message": "Invalid Token"
    }
  ]
}
```
```

--------------------------------

### Create Intent for Account Aggregation - JSON

Source: https://docs.tarabut.com/docs/handling-multiple-use-cases

Example JSON request body for the Create Intent API, specifically for the `ACCOUNT_AGGREGATION` use case. It includes user details, provider information, consent parameters with `purposeStatement`, `product`, `entryPoint`, and a detailed `permissionsList`.

```json
{
	"user": {
		"customerUserId": "38737982364",
		"firstName": "John",
		"lastName": "Snow",
		"email": "some@email.com"
	},
	"providerType": "Retail",
	"consent": {
		"providerId": "BLUE",
		"flowType": "TPP_MANAGED",
		"tppDetails": {
			"tradingName": "TPP tradingName",
			"legalName": "TPP legalName",
			"identifier": {
				"type": "Other",
				"value": "TPP CR Number"
			},
			"purposeStatement": "ACCOUNT_AGGREGATION",
			"product": "BANK_ACCOUNTS_AGGREGATION",
			"entryPoint": "CONSENT_MANAGEMENT"
		},
		"permissionsList": [
			"ReadAccountsBasic",
			"ReadAccountsDetail",
			"ReadBalances",
			"ReadTransactionsBasic",
			"ReadTransactionsDetail",
			"ReadTransactionsCredits",
			"ReadTransactionsDebits",
			"ReadBeneficiariesBasic",
			"ReadBeneficiariesDetail",
			"ReadScheduledPaymentsBasic",
			"ReadScheduledPaymentsDetail",
			"ReadDirectDebits",
			"ReadStandingOrdersBasic",
			"ReadStandingOrdersDetail"
		]
	},
	"language": "EN",
	"redirectUrl": "http://myredirectURL.me"
}
```

--------------------------------

### Get Transactions Request (cURL)

Source: https://docs.tarabut.com/v1.0/docs/get-data-via-connect

This cURL command demonstrates how to make a GET request to retrieve categorized transactions from a specific linked account. It requires an authorization token and the account ID.

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

--------------------------------

### Create Single Domestic Payment Request (Ruby)

Source: https://docs.tarabut.com/v1.0/reference/merchant-single-payments

Example of initiating a single domestic payment request using Ruby. This snippet uses the 'httparty' gem to make a POST request to the Tarabut Gateway API. It includes the necessary headers and a JSON payload, demonstrating a common pattern for API interactions in Ruby. Ensure 'httparty' is installed.

```ruby
require 'httparty'

def create_payment_request(currency, expiration_value, expiration_unit)
  url = 'https://sandbox.payments.tarabutgateway.io/api/v1/payments'
  headers = {
    'accept' => 'application/json',
    'content-type' => 'application/json',
    'Idempotency-Key' => 'your-unique-idempotency-key',
    'Authorization' => 'Bearer your-access-token'
  }
  payload = {
    'currency' => currency,
    'expiration' => {
      'unit' => expiration_unit,
      'value' => expiration_value
    }
  }

  begin
    response = HTTParty.post(url, headers: headers, body: payload.to_json)
    if response.success?
      puts "Payment request created: #{response.parsed_response}"
      return response.parsed_response
    else
      puts "Error creating payment request: #{response.code} - #{response.body}"
      return nil
    end
  rescue Net::HTTPError => e
    puts "Network error: #{e.message}"
    return nil
  end
end

# Example usage:
# payment_details = create_payment_request('BHD', 30, 'MINUTES')
# puts payment_details if payment_details
```
Tokens:
Raw