Retrieve Account & Transaction Data
Retrieve account, balance, and transaction data for the consented accounts.
Pre- requisite
- Open Banking Consent journey should be successfully completed.
- Generate access token using the Generate Access Token endpoint before making any data retrieval calls and ensure using the same customer identifier that was used in the created consent.
:blue-book: Accounts and Balance Endpoints
The following is the list of accounts and balance endpoints:
| Endpoint | Description |
|---|---|
| Get Accounts | Retrieve a list of the connected accounts across all consents. Key details include account type, identifier (such as IBAN), provider bank, etc. Note: if the account is associated with multiple consents, the endpoint will return unique account details (account details will not be duplicated) |
| Get Account Balance | Retrieve the account balance details. Key details include balance type, currency, amount, etc. |
| Refresh Account Balance | Retrieve the latest account balance from the bank without waiting for daily data synchronization |
:blue-book: Transactions Endpoints
The following is the list of transaction endpoints:
| Endpoint | Description |
|---|---|
| Get Account Raw Transactions | Retrieve basic transaction data for each consented account. Key details include transaction amount and currency, time, credit or debit, etc. |
| Get Account Transactions | Retrieve robust transaction data enriched with attributes from Tarabut's Insights service such as transaction category and merchant details. |
| Refresh Account Transactions | Retrieve the latest transactions from the bank without waiting for daily data synchronization. Note: this endpoint will retrieve the basic transaction, to get enriched transactions you have to call the Get Account Transactions endpoint after refreshing the transactions. |
💡 Which Transaction endpoint should I use?
Account Raw Transactions or Account Transactions
Refresh Account Transactions
💡 How do I know when customer data was last synced?
Transactions Data
You can find out the last update time for the Get Account Raw Transactions, Get Account Transactions and Refresh Account Transactions in the meta object, where there is a lastTransactionsUpdateDatetime property that specifies when the data was last updated. The following example is the Get Account Transactions response:
{
"transactions": [
{
"transactionId": "7966ce3b-65ef-44e3-ac8a-5c12452ab1e9",
"accountId": "7eeec027-16d2-41bf-abad-70a81aabb2b3",
"providerId": "BLUE",
"transactionDescription": "PURCHASE 3LINES RESTAURANT",
"transactionType": "POS",
"subTransactionType": "Purchase",
"category": {
"group": "Expense",
"name": "Eating Out",
"icon": "https://tg-merchants-prod.s3.me-south-1.amazonaws.com/category/EXPENSE_EATING_OUT.svg"
},
"merchant": {
"name": "",
"logo": "",
"merchantCategoryCode": ""
},
"creditDebitIndicator": "Debit",
"amount": {
"value": 3.045,
"currency": "SAR"
},
"bookingDateTime": "2023-10-16T00: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"
}
]
}
Sync Transactions Data
You can sync the transactions data without waiting for daily data synchronization by calling Refresh Account Transactions endpoint, you will get the latest transactions from bank
Account Data
Also, you can find out when the account data was last updated, by checking the lastUpdatedDateTime property in the Get Accounts response:
{
"accounts": [
{
"accountId": "c0960f92-b2fa-4e34-bc1b-f081b8587e0a",
"accountHolderName": "Ibrahim Adil",
"accountProductType": "CreditCard",
"accountDescription": "Ibrahim Adil - SAR Credit Card (thin file)",
"providerId": "BLUE",
"lastUpdatedDateTime": "2023-09-27T20:21:34.487Z",
"consents": [
{
"id": "8e44864f-b5f9-4187-951d-a2d7d1d2809e",
"expiryDate": "2025-01-14T08:51:51.144Z",
"status": "ACTIVE"
}],
"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"
}
}
]
}
Balance Data
You can find out when the balance data was last updated, by checking the lastBalancesUpdateDatetime property in the Get Account Balance response:
{
"balances": [
{
"type": "ClosingAvailable",
"amount": {
"value": 330.34,
"currency": "SAR"
}
}
],
"meta": {
"lastBalancesUpdateDatetime": "2024-04-16T10:08:49.752196Z"
}
}
Sync Balance Data
You can sync the account balance data without waiting for daily data synchronization by calling Refresh Account Balance endpoint, you will get the customer's current balance (in real-time)
Updated 7 days ago