Retrieve available balances across all customer accounts associated with a consent to assess funds availability and overall financial position
Balance Check service provides a consolidated view of account balances across all accounts linked to an authorized consent. This enables applications to evaluate available funds, assess financial health, and support eligibility, affordability, and verification workflows without retrieving balances account by account.
Balance Check service aggregates balance information across all customer accounts associated with a consent.
Using this service, you can:
The response includes both account-level balance information and consolidated balance totals.
This API can only be accessed using a valid and active consent. Before accessing this service, ensure that a consent has been created and authorized with the required useCaseType and permissions.
The consent must include the appropriate useCaseType and permission values that allow access to the corresponding financial data services.
If you do not already have a consent with the required configuration, you must first create one using the Create Consent API and ensure that it is successfully authorized. Once the consent becomes active, the generated consentId can be used to access this API service.
Scope | useCaseType | Permissions |
|---|---|---|
To access Balance Check service under Data Use Case APIs |
|
|
This service requires consentId and returns all balances of accounts associated with that consent.
Endpoint URL | Method |
|---|---|
| GET |
The following headers must be included when calling the Balance API.
Header parameter | Description |
|---|---|
| Access token used to authenticate the API request |
curl --request GET \
--url 'https://obsandbox.onesingleview.com/v2/api/observice/allAccountsBalance?dateTimeStamp=2023-06-14T17%3A51%3A03&requestID=db35902b-806a-4141-b1e2-e93f60c82f62&merchantId=APIU-300356&balanceCheck=true&bankCode=SVMOB1&consentId=urn%3ASABBSARI%3Akac-cd3b9a37-eb97-4a70-b268-38af9f2950b1' \
--header 'accept: application/json' \
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiTDNyMmpxV29JS2I4MTNodDBNYVR4WGpBZU5qU1FWaTFad3B5QnlkOVpHelZXR2ZwUmFQNUZ1TTJ6NmIzbi9WVE1aK1FucERJMEZXWWN6VGJsOEc5cXhaY0VLUTZZWEFsYmZnejdkdlFpTTRXeVBNalQ2WG1NUDh5YXI4RDVWZTUwUGhYbDcwYkYxRENJeEpDaU5TVkhBKytXYnRUZkhDblVBPT0iLCJpYXQiOjE3ODE1OTAwMDksImV4cCI6MTc4MTU5MzYwOX0.MO69uVzXyHqN2UBxvxCn3sBZcOpNWYP7bsQPe-qdGsQ'Request parameters
Parameters | Requirement | Description | Data type | Data validation |
|---|---|---|---|---|
dateTimeStamp | Mandatory | Indicates the date and time when the request is created | Date | ISO 8601 format |
requestID | Mandatory | Unique identifier for the request used for tracking and traceability | Alphanumeric | UUID format |
merchantID | Mandatory | Identifier assigned to the merchant or client application initiating the request | String |
|
balanceCheck | Mandatory | Specification of data use case API | Enum |
|
bankCode | Mandatory | Unique bank identifier code | Enum |
|
consentId | Mandatory | Unique identifier of the consent | String |
|
{
"success": true,
"payload": [
{
"code": "SVMOB1",
"consentId": "urn:SABBSARI:kac-cd3b9a37-eb97-4a70-b268-38af9f2950b1",
"data": {
"account": [
{
"accountId": "dd11ad81-e172-4121-b6fe-2461a5cfff52",
"accountHolderName": "Habib Al-Sagga",
"accountHolderShortName": "Habib Al-Sagga",
"status": "Active",
"currency": "SAR",
"nickname": "Habib Al-Sagga",
"accountType": "Personal",
"accountSubType": "",
"accountIdentifiers": [
{
"identificationType": "KSAOB.IBAN",
"identification": "00000250000002",
"name": "Habib Al-Sagga"
}
],
"servicer": {
"identificationType": "KSAOB.BICFI",
"identification": "10000109010101"
},
"statusUpdateDateTime": "2023-07-11T07:48:38.115Z",
"description": "Account sub-type description",
"openingDate": "2022-09-15T07:48:38.115Z",
"maturityDate": "2024-05-07T07:48:38.115Z",
"balance": [
{
"amount": {
"amount": "1500.00",
"currency": "SAR"
},
"creditDebitIndicator": "KSAOB.Credit",
"type": "KSAOB.ClosingAvailable",
"dateTime": "2016-07-21T00:00:00.000Z",
"creditLine": [
{
"included": true,
"type": "KSAOB.Temporary",
"amount": {
"amount": "500.00",
"currency": "SAR"
}
}
]
}
]
}
],
"totalOpeningBalance": 1500,
"totalAvailableBalance": 1500,
"totalClosingAvailable": 1500,
"currency": "SAR"
},
"links": {
"self": "https://rs1.sandbox.sabb.com/open-banking/account-information/2022.11.01-final-errata2/accounts"
},
"meta": {
"totalPages": 1
}
}
],
"overAllBalance": {
"totalOpeningBalance": 1500,
"totalAvailableBalance": 1500,
"totalClosingAvailable": 1500,
"currency": "SAR"
}
}Response parameters
Parameter | Description | Data type | Data validation |
|---|---|---|---|
success | Indicates whether the request was successfully processed | Enum |
|
payload | Contains account information grouped by bank | Array of objects |
|
code | Bank identifier associated with the account data | Enum |
|
data | Contains account details returned from the bank | Object |
|
account | List of accounts associated with the consent | Array of objects |
|
accountId | Unique identifier of the account | String |
|
accountHolderName | Full name of the account holder | String |
|
accountHolderShortName | Short or display name of the account holder | String |
|
status | Current status of the account | Enum |
|
currency | Currency in which the account operates | String |
|
nickname | Nickname assigned to the account | String |
|
accountType | Specifies the type of accounts that can be accessed | Enum |
|
accountSubType | Specifies the type of accounts that can be accessed | Enum |
|
accountIdentifiers | Each account may contain one or more identifiers that uniquely identify the account | Object |
|
identificationType | Type of identifier used | String |
|
identification | Identifier value associated with the account | String |
|
name | Name associated with the identifier | String |
|
servicer | This contains information about the financial institution servicing the account | Object |
|
identificationType | Type of bank identifier used | String |
|
identification | Identifier value of the servicing institution | String |
|
statusUpdateDateTime | Date and time when the account status was last updated by the servicing bank | Date | ISO 8601 format |
description | Additional information or description associated with the account subtype or account characteristics | String |
|
openingDate | Date and time when the account was originally opened at the bank | Date | ISO 8601 format |
maturityDate | Date when the account reaches maturity. This field is typically applicable for term-based accounts. | Date | ISO 8601 format |
balance | Tag carrying account balance information | Object |
|
amount | Tag carrying cash balance information | String |
|
amount | Cash balance amount | Object |
|
currency | Default currency of the account in which the balance is indicated | Integer |
|
creditDebitIndicator | Indicates whether the balance is a credit or a debit balance |
|
|
type | Indicator type details |
|
|
dateTime | Date and time information of the indicator |
|
|
creditLine | Tag carrying credit line information |
|
|
included | Status of credit line as |
|
|
type | Type of credit line details |
|
|
amount | Tag carrying amount information of credit line |
|
|
amount | Available amount in credit line |
|
|
currency | Currency in which the credit line balance is indicated |
|
|
totalOpeningBalance | Total opening balance |
|
|
totalAvailableBalance | Total available balance |
|
|
totalClosingAvailable | Total closing balance |
|
|
currency | Currency of the total balances |
|
|
links | Redirect link |
|
|
self | Own link/URL details |
|
|
meta | Meta tag |
|
|
totalPages | Information displayed in terms of pages |
|
|
overallBalance | Tag carrying information on overall balances |
|
|
totalOpeningBalance | Total opening balance |
|
|
totalAvailableBalance | Total available balance |
|
|
totalClosingBalance | Total closing balance |
|
|
currency | Currency of the overall balance indicated |
|
|