Balance Enquiry

Retrieve single or multiple bank account balances

SingleView B2B API services Balance Enquiry allows users with access to request and retrieve specific user bank account balances. Corporate Customers can use this B2B service to enquire about their real-time account Information, which includes Customer Name, Account Status, Account Number, Account Currency, and Available Balance.

📘

Mandatory information

  • The user must provide the valid credentials in the header
  • Encrypted and valid Signature and an active "Access Token"
  • Request format as specified with all the mandatory details with appropriate request tags
🌐

Domain details

EnvironmentDomainRate/Limit
Sandboxsandboxapi.onesingleview.com10 Calls per Minute
Production/LIVETo be provided upon onboardingBased on contract

Get Balance Enquiry

Endpoint details

Endpoint URL

Method

Authentication requirements

/api/v1/account/balance

POST

1. CompanyId
2. SVReferenceID
3. DateTimeStamp
4. Device
5. Authorization: Bearer (Token)

Sample request

curl --location 'https://sandboxapi.onesingleview.com/api/v1/account/balance' \
--header 'CompanyId: MYCOMPANY'
--header 'SVReferenceID: SV150619940615'
--header 'DateTimeStamp	:2025-01-02T10:20:39'
--header 'Device: Web'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiTDNyMmpxV29JS2I4MTNodDBNMlZ4WGpFZmR6WFNWaTFad3B5QnlkOVpHelZXR2ZwUmFQNUV1TXl6S1Aybi94Y0lwR2V5STNNMkdPL1pqakd4ZG0yclJKUkdhRXlaWGNpWnZnOHArMWIyOGtOQTVkZ0VKajVVSEdiTmtNPSIsImlhdCI6MTczNTgwMTQ3NywiZXhwIjoxNzM1ODA1MDc3fQ.Bh7LFkvxNFrLe9dmH5rURWjGpES-u4z2EGeyrNM7z6E'
--header 'Content-Type: application/json' \
--data '{
"Message": {
  "OSVBalanceEnquiryRequest": {
    "StartDate": "2025-01-28T08:00:00",
    "TransactionType": "940",
    "OSVPaymentInfoMessage": [
      {
        "OSVPaymentInfoRequest": {
          "AccountNumbers": {
            "AccountNumber": [
              {
                "AccNumber": "2011639269901"
              }
            ]
          },
          "BankCode": "RIYADH",
          "CompanyCode": "FIFC001"
        }
      }
    ],
    "EndDate": "2025-01-28T12:00:00"
  }
},
"Signature": "FuJPkgDw2U0ZruL2TnIypUqqbdu9/KpGFX0tLns0rtvlOKR/2PKsJbgxWdIhJXvXwx8tG6b0JPr4M/afkGXkm6j5ua7VC3Z8L2k6amycZ9gCZU1uCyPYI8LRhod79jGOZIbQRY8CQj7uRqT/eKZWlwLf5qhKY7Tf0n6yBhaH51qfvlCzB6BW0Ol0riclN51VQOhKjqHQ25PRbFzu4BDUURm+z/4fJY9kKkWdDbwxoov1+AGDeu/sz0kG/lJK69ra1UXwkOtiAZk5VmnsfrkqCIVQqDsim/yAN5dVeI7Yw3ZTXGtOX4FKSp+0mCW+sfLoKhCaBwG/dbBMx6lkQqF+sg=="
}'

Request description:

JSON Tag

Description

Data type

Message Mandatory

Header information (client credentials)

Object & String

OSVBalanceEnquiryRequest
Mandatory

Root node

Object

StartDate
Mandatory

Initial or starting date of the mentioned period
ISO 8601 format - YYYY-MM-DDTHH:MM:SS

Date

EndDate
Mandatory

Final or last date of the mentioned period
ISO 8601 format - YYYY-MM-DDTHH:MM:SS

Date

TransactionType
Mandatory

Always it should be BE

String

OSVPaymentInfoMessage
Mandatory

This tag contains multiple banks requests

Object

OSVPaymentInfoRequest
Mandatory

Element root

Object

BankCode
Mandatory

Unique bank identification code
Ex:ALRAJHI, SABB, BSF, ANB, SNB, ALINMA, GIB, RIYADH, ALBI, BJAZ

Alphanumeric

CompanyCode
Mandatory

Sender company code/Identifier provided by the bank during on-boarding

Alphanumeric

B2BUserId
Conditional for ICICI

Unique B2B user identification details

String

B2BUrn
Conditional for ICICI

Unique B2B reference number

String

B2BAggrId
Conditional for ICICI

Unique B2B aggregator identification details

String

AccountNumbers
Mandatory

Tag carrying information on account numbers

Array/Object

AccountNumber
Mandatory

Tag carrying account number details

Object

AccNumber
Mandatory

Unique account number to request balance

  • Input size:
    Min - 11 Characters
    Max - 24 Characters_

Alphanumeric

Signature
Mandatory

Encrypted string generated using a Private Key/CA-Signed Certificate with SHA-256 and RSA (JCE Signature)

String

Sample responses

{
  "OSVBalanceEnquiryResponse": {
    "BalanceEnquiryResponseMessage": [
      {
        "BankCode": "RIYADH",
        "CompanyCode": "FIFC001",
        "StatusCode": "OK",
        "StatusDetail": "Success",
        "ResponseItemCount": "01",
        "TotalAvailableBalance": 3405688934.32,
        "TotalOpeningBalance": 3405688934.32,
        "TotalClosingBalance": 0,
        "BalanceEnquiryResponse": [
          {
            "SequenceNum": "",
            "ReceiptTime": "2025-01-28T14:09:20",
            "AccountNumber": "2011639269901",
            "AccountCurrency": "SAR",
            "AccountStatus": "00",
            "AccountStatusDesc": "Savings Account",
            "AccountType": "CA",
            "AuthorizedOdLimit": "00.00",
            "AvailableBalance": 3405688934.32,
            "OpeningBalance": 3405688934.32,
            "ClosingBalance": 0,
            "DebitAllowed": true,
            "CreditAllowed": true,
            "StatusCode": "OK",
            "StatusDetail": "Success"
          }
        ]
      }
    ]
  }
}
{
  "OSVBalanceEnquiryResponse": {
    "BalanceEnquiryResponseMessage": [
      {
        "BankCode": "ALRAJHI",
        "CompanyCode": "125001291",
        "StatusCode": "Failed",
        "StatusDetail": null,
        "ResponseItemCount": "",
        "TotalAvailableBalance": "",
        "TotalOpeningBalance": "",
        "TotalClosingBalance": "",
        "BalanceEnquiryResponse": [
          {
            "SequenceNum": "",
            "ReceiptTime": null,
            "AccountNumber": "01080573862900141",
            "AccountCurrency": null,
            "AccountStatus": "",
            "AccountStatusDesc": "",
            "AccountType": null,
            "AuthorizedOdLimit": "",
            "AvailableBalance": "",
            "OpeningBalance": "",
            "ClosingBalance": null,
            "DebitAllowed": true,
            "CreditAllowed": true,
            "StatusCode": "Failed",
            "StatusDetail": "Invalid Account Number"
          }
        ]
      }
    ]
  }
}

Response description

JSON Tag

Description

Data type

OSVBalanceEnquiryResponse

Root node

Object

BalanceEnquiryResponseMessage

Element root containing response of every bank

Object

BankCode

Unique bank identification code
Ex: ALRAJHI, SABB, BSF, ANB, NCB, ALINMA, GIB, RIYADH, ALBI, BJAZ

String

CompanyCode

Sender company code/Identifier provided by the bank during on-boarding

String

B2BAggrId

Unique B2B aggregator identification

String

B2BUserId

Unique B2B user identification details

String

StatusCode

Code representing the status of the request processed

String

StatusDetail

Details of the response

String

ResponseItemCount

Number of balance items fetched in the response

String

TotalAvailableBalance

Total available balance

String

TotalOpeningBalance

Total opening balance

String

TotalClosingBalance

Total closing balance

String

BalanceEnquiryResponse

This tag contains the details of the requested Bank Accounts

String

SequenceNum

Count of the accounts per the bank

String

ReceiptTime

Receipt Time of the Enquiry

String

AccountNumber

Account Number

String

AccountCurrency

Account Currency. Maximum length of Currency should be 3. E.g. SAR

String

AccountType

Account Type
CA - Current Account
SA - Savings Account

String

AccountStatus

Status of the Account
00 - ACTIVE
01 - DORMANT
02 - UNCLAIMED
03 - CLOSING
04 - CLOSED
05 - BLOCKED
06 - DECEASED
07 - INVALID

String

AccountStatusDesc

Reason for the Corresponding Account Status

String

AvailableBalance

Available Balance in Account (i.e)
(Ledger Balance + OD limit) - Booked balance

String

OpeningBalance

Opening Balance

String

ClosingBalance

Closing Balance

String

DebitAllowed

Debit is allowed from the account or not. The value will be either true or false

Boolean

CreditAllowed

Credit is allowed to the account or not. The value will be either true or false

Boolean

StatusCode

Status Code displayed as OK or Failed

String

StatusDetail

Status details of the code displayed

String