Balance Check

Get account balance updates in real-time

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

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

Get Balance Check Services

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 TagDescription
successProcess success status represented as True or False
payloadPayload tag carrying response information
codeUnique bank code identification
dataTag carrying accounts and balances data included in the response
accountIdUnique account identification
accountHolderNameName of the account holder
accountHolderShortNameShort name of the account holder
statusStatus of the account
currencyDefault currency of the account
nicknameNickname of the account
accountTypeDetails of account type
accountSubTypeDetails of account sub-type
accountIdentifiersTag carrying account identifiers details
identificationTypeAccount identification type details
identificationAccount identification details
nameName of the account identifier
servicerTag carrying account servicer details
identificationTypeServicer identification type details
identificationServicer identification details
statusUpdateDateTimeLast time and date of update for account information
descriptionDescription of the update
openingDateOpening date of the account
maturityDateMaturity date of the account
balanceTag carrying account balance information
amountTag carrying cash balance information
amountCash balance amount
currencyDefault currency of the account in which the balance is indicated
creditDebitIndicatorIndicates whether the balance is a credit or a debit balance
typeIndicator type details
dateTimeDate and time information of the indicator
creditLineTag carrying credit line information
includedStatus of credit line as included or excluded
typeType of credit line details
amountTag carrying amount information of credit line
amountAvailable amount in credit line
currencyCurrency in which the credit line balance is indicated
totalOpeningBalanceTotal opening balance
totalAvailableBalanceTotal available balance
totalClosingAvailableTotal closing balance
currencyCurrency of the total balances
linksRedirect link
selfOwn link/URL details
metaMeta tag
totalPagesInformation displayed in terms of pages
overallBalanceTag carrying information on overall balances
totalOpeningBalanceTotal opening balance
totalAvailableBalanceTotal available balance
totalClosingBalanceTotal closing balance
currencyCurrency of the overall balance indicated