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:

EndpointDescription
Get AccountsRetrieve account details for each consented account. 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 Holder NameRetrieve account holder name details.
Get Account BalanceRetrieve the account balance details. Key details include balance type, currency, amount, etc.

:blue-book: Transactions Endpoints

The following is the list of transaction endpoints:

EndpointDescription
Get Account Raw TransactionsRetrieve basic transaction data for each consented account. Key details include transaction amount and currency, time, credit or debit, etc.
Get Account TransactionsRetrieve robust transaction data enriched with attributes from Tarabut's Insights service such as transaction category and merchant details.
Refresh Account TransactionsRetrieve 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.

:bulb: Which Transaction endpoint should I use?

Account Raw Transactions or Account Transactions

Raw Transactions vs Enriched Transactions

Refresh Account Transactions

Refresh Account Transactions

:bulb: 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": ""
      },
      "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"
    }
  ]
}

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",
      "accountProductType": "CreditCard",
      "accountDescription": "Ibrahim Adil - SAR Credit Card (thin file)",
      "providerId": "BLUE",
      "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"
      }
    }
  ]
}

ℹ️

Balance Data

Every time you call the Get Account Balance endpoint, you will receive the customer's current balance (in real-time)