Introduction

Balance Check API services provide access to real-time balance information for specific bank accounts included in the Consent ID. Viewing multiple account balances in real time is helpful in budgeting, payment processing, and account management. SingleView's user-friendly integration options and security measures make our API services a valuable resource for businesses and individuals to stay informed about their financial positions.

Balance Check API services allow you to fetch single or multiple account balances in real time.

Consent

User consent is the primary requirement to access any services in Open Banking. The user or account holder grants explicit consent to a Third-Party to access their financial data. This consent is given through a secure, multi-factor authentication process to verify the user's identity.

The consent request must include the following details:

Endpoint	`useCaseType` Value	`permissions` Value
`/v1/api/observice/connect`	`BALANCECHECK`	`ReadAccountsBasic` `ReadAccountsDetail` `ReadBalances`

Endpoint

useCaseType

Value

permissions

Value

/v1/api/observice/connect

BALANCECHECK

ReadAccountsBasic
ReadAccountsDetail
ReadBalances

Check Consent Management for more details to create, view, and revoke consents.

Get Balance Check Services

Try in API Reference ➜

Endpoint details

Endpoint URL	Method	Authentication requirements
`/v1/api/observice/allAccountsBalance`	POST	1. `clientId` 2. `clientCode` 3. `signature` 4. `Authorization Bearer: Token`

Sample request

{
  "dateTimeStamp": "2024-12-31T10:40:00+02:00",
  "requestID": "df797efb-b588-4234-8ae1-5cb748559830",
  "merchantId": "APIS-300505",
  "fromDate": "2016-01-01T10:40:00+02:00",
  "toDate": "2025-12-31T10:40:00+02:00",
  "balanceCheck" : true,
  "banks": [
    {
      "code": "SAMA",
      "consentId":"urn:SAMA:kac-5a166b7d-8cdb-443a-a67a-80ad7a5b95b3"
    }
  ]
}

Request description

JSON Tag	Description	Data type
DateTimeStamp Mandatory	Stamp denoting the date and time of the request ISO 8601 format - YYYY-MM-DDTHH:MM:SS	Date
RequestID Mandatory	Unique request identification UUID format	Alphanumeric
merchantId Mandatory	Unique merchant identification UUID format	Alphanumeric
fromDate Mandatory	Initial date of transaction period ISO 8601 format - YYYY-MM-DDTHH:MM:SS	Date
toDate Mandatory	Final date of transaction period ISO 8601 format - YYYY-MM-DDTHH:MM:SS	Date
balanceCheck Mandatory	Balance check service tag to be denoted as `true`	Boolean
banks Mandatory	Array of banks and consents	Object
code Mandatory	Unique bank identification code	Alphanumeric
consentId Mandatory	Unique consent identification	String

Sample response

{
  "payload": {
    "success": true,
    "payload": [
      {
        "code": "SAMA",
        "consentId": "urn:SAMA:kac-e17407a4-283d-4ae2-9764-64c632e2e390",
        "data": {
          "account": [
            {
              "accountId": "100004000000000000000002",
              "accountHolderName": "Mitsuhirato",
              "accountHolderShortName": "Mitsuhirato",
              "status": "Active",
              "currency": "SAR",
              "nickname": "Mitsuhirato",
              "accountType": "KSAOB.Retail",
              "accountSubType": "CurrentAccount",
              "accountIdentifiers": [
                {
                  "identificationType": "KSAOB.IBAN",
                  "identification": "10000109010102",
                  "name": "Luigi International"
                },
                {
                  "identificationType": "KSAOB.IBAN",
                  "identification": "10000109010102",
                  "name": "Luigi International"
                }
              ],
              "servicer": {
                "identificationType": "KSAOB.BICFI",
                "identification": "10000109010101"
              },
              "statusUpdateDateTime": "2023-02-01T16:37:00.980Z",
              "description": "Account sub-type description",
              "openingDate": "2022-04-08T16:37:00.980Z",
              "maturityDate": "2023-11-29T16:37:00.980Z",
              "balance": [
                {
                  "amount": {
                    "amount": "1091.70",
                    "currency": "SAR"
                  },
                  "creditDebitIndicator": "KSAOB.Credit",
                  "type": "KSAOB.ClosingAvailable",
                  "dateTime": "2022-09-14T09:55:54.217Z",
                  "creditLine": [
                    {
                      "included": true,
                      "type": "KSAOB.Temporary",
                      "amount": {
                        "amount": "1000.00",
                        "currency": "SAR"
                      }
                    }
                  ]
                }
              ]
            },
            {
              "accountId": "100004000000000000000003",
              "accountHolderName": "Mitsuhirato",
              "accountHolderShortName": "Mitsuhirato",
              "status": "Active",
              "currency": "SAR",
              "nickname": "Mitsuhirato",
              "accountType": "KSAOB.Retail",
              "accountSubType": "CurrentAccount",
              "accountIdentifiers": [
                {
                  "identificationType": "KSAOB.IBAN",
                  "identification": "10000109010103",
                  "name": "Mario International"
                },
                {
                  "identificationType": "KSAOB.IBAN",
                  "identification": "10000109010103",
                  "name": "Mario International"
                }
              ],
              "servicer": {
                "identificationType": "KSAOB.BICFI",
                "identification": "10000109010101"
              },
              "statusUpdateDateTime": "2023-02-01T16:37:00.981Z",
              "description": "Account sub-type description",
              "openingDate": "2022-04-08T16:37:00.981Z",
              "maturityDate": "2023-11-29T16:37:00.981Z",
              "balance": [
                {
                  "amount": {
                    "amount": "1230.00",
                    "currency": "SAR"
                  },
                  "creditDebitIndicator": "KSAOB.Credit",
                  "type": "KSAOB.ClosingAvailable",
                  "dateTime": "2017-04-05T10:43:07+00:00",
                  "creditLine": [
                    {
                      "included": true,
                      "type": "KSAOB.Temporary",
                      "amount": {
                        "amount": "1000.00",
                        "currency": "SAR"
                      }
                    }
                  ]
                }
              ]
            }
          ],
          "totalOpeningBalance": 2321.7,
          "totalAvailableBalance": 2321.7,
          "totalClosingAvailable": 2321.7,
          "currency": "SAR"
        },
        "links": {
          "self": "https://rs1.lab.openbanking.sa/open-banking/account-information/2022.11.01-final-errata2/accounts"
        },
        "meta": {
          "totalPages": 1
        }
      }
    ],
    "overAllBalance": {
      "totalOpeningBalance": 2321.7,
      "totalAvailableBalance": 2321.7,
      "totalClosingAvailable": 2321.7,
      "currency": "SAR"
    }
  }
}

Response description

JSON Tag	Description
success	Process success status represented as `True` or `False`
payload	Payload tag carrying response information
code	Unique bank code identification
data	Tag carrying accounts and balances data included in the response
accountId	Unique account identification
accountHolderName	Name of the account holder
accountHolderShortName	Short name of the account holder
status	Status of the account
currency	Default currency of the account
nickname	Nickname of the account
accountType	Details of account type
accountSubType	Details of account sub-type
accountIdentifiers	Tag carrying account identifiers details
identificationType	Account identification type details
identification	Account identification details
name	Name of the account identifier
servicer	Tag carrying account servicer details
identificationType	Servicer identification type details
identification	Servicer identification details
statusUpdateDateTime	Last time and date of update for account information
description	Description of the update
openingDate	Opening date of the account
maturityDate	Maturity date of the account
balance	Tag carrying account balance information
amount	Tag carrying cash balance information
amount	Cash balance amount
currency	Default currency of the account in which the balance is indicated
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 `included` or `excluded`
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