Balance enquiry (V2 - Draft)

note

This is a draft version of the Balance Enquiry V2 API. The final version is expected to be released soon. The API specifications are subjected to go through a few more changes before the final version is released.
Refer previous version - Balance Enquiry V1

Balance Enquiry API enables businesses to retrieve the available balance of a bank account associated with their company. The API validates the request, forwards the balance enquiry to the specified bank, and returns the account balance along with the processing status.

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
Ensure the BankCode, CompanyCode, and AccountNumber are valid and correctly formatted
AvailableBalance is returned within BalanceEnquiryInfo for successful requests
The ErrorCode field is empty when the request is successfully completed
Do not interpret Response_Timeout as confirmation that the balance enquiry failed at the bank. The bank's final processing status may require a subsequent enquiry or retry
Error codes beginning with ERR are bank-provided errors, while MW-XXX errors are generated by SingleView's validation layer
Response timestamps are returned in the format YYYY-MM-DDTHH:mm:ss

🌐 Domain details
Environment
Domain
Rate/Limit
Sandbox
sandboxapi.onesingleview.com
3 Calls per Day
Production/LIVE
To be provided upon onboarding
Based on contract

Environment	Domain	Rate/Limit
Sandbox	sandboxapi.onesingleview.com	3 Calls per Day
Production/LIVE	To be provided upon onboarding	Based on contract

Get balance enquiry

Endpoint details

Endpoint URL	Method	Authentication requirements
`/api/v2/balance`	POST	`CompanyId` `SVReferenceID` `DateTimeStamp` `Device` `Authorization: Bearer` (Token)

Sample request

Request to perform balance enquiry

curl --location 'https://sandboxapi.onesingleview.com/api/v2/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": {
        "TransactionType": "BE",
        "BankCode": "RIYADH",
        "CompanyCode": "COMPANY001",
        "AccountNumber": "2011123456789"
    }
},
"Signature": "FuJPkgDw2U0ZruL2TnIypUqqbdu9/KpGFX0tLns0rtvlOKR/2PKsJbgxWdIhJXvXwx8tG6b0JPr4M/afkGXkm6j5ua7VC3Z8L2k6amycZ9gCZU1uCyPYI8LRhod79jGOZIbQRY8CQj7uRqT/eKZWlwLf5qhKY7Tf0n6yBhaH51qfvlCzB6BW0Ol0riclN51VQOhKjqHQ25PRbFzu4BDUURm+z/4fJY9kKkWdDbwxoov1+AGDeu/sz0kG/lJK69ra1UXwkOtiAZk5VmnsfrkqCIVQqDsim/yAN5dVeI7Yw3ZTXGtOX4FKSp+0mCW+sfLoKhCaBwG/dbBMx6lkQqF+sg=="
}'

Request parameters

JSON Tag	Requirement	Description	Data type
Message	Mandatory	Header information (client credentials)	Object
OSVBalanceEnquiryRequest	Mandatory	Tag carrying request information for balance enquiry	Object
TransactionType	Mandatory	Transaction type specification to be provided as `BE`	String
BankCode	Mandatory	Unique bank identification code `ALRAJHI` - Al Rajhi Bank `SABB` - Saudi Awaal Bank `BSF` - Banque Saudi Fransi `ALINMA` - Arab National Bank `ANB` - Arab National Bank `NCB` - Saudi National Bank `RIYADH` - Riyadh Bank `GIB` - Gulf International Bank `BJAZ` - Bank Al Jazira `ALBI` - Bank Al Bilad `D360` - D360 Bank	String
CompanyCode	Mandatory	Sender company code/Identifier provided by the bank during on-boarding	String
AccountNumber	Mandatory	Valid bank account number Input size: Min - 11 Characters Max - 24 Characters	String
Signature	Mandatory	Encrypted string generated using a Private Key/CA-Signed Certificate with SHA-256 and RSA (JCE Signature)	String

Sample responses

{
    "OSVBalanceEnquiryResponse": {
        "BankCode": "RIYADH",
        "CompanyCode": "COMPANY0",
        "AccountNumber": "2011123456789",
        "StatusCode": "Completed",
		"ErrorCode": "",
        "StatusDetail": "Account balance fetched successfully.",
        "TimeStamp": "2025-02-28T07:35:25",
        "BalanceEnquiryInfo": {
            "AvailableBalance": "3405688934.32"
        }
    }
}

Response parameters

JSON Tag	Description	Data type
OSVBalanceEnquiryResponse	Tag carrying information on balance enquiry response	Object
BankCode	Unique bank identification code `ALRAJHI` - Al Rajhi Bank `SABB` - Saudi Awaal Bank `BSF` - Banque Saudi Fransi `ALINMA` - Arab National Bank `ANB` - Arab National Bank `NCB` - Saudi National Bank `RIYADH` - Riyadh Bank `GIB` - Gulf International Bank `BJAZ` - Bank Al Jazira `ALBI` - Bank Al Bilad `D360` - D360 Bank	String
CompanyCode	Sender company code/Identifier provided by the bank during on-boarding	String
AccountNumber	Account number passed in the request for balance enquiry	String
StatusCode	Code representing the status of the request processed	String
ErrorCode	Value representing the Error code obtained only for failed scenarios	String
StatusDetail	Details of the response	String
TimeStamp	Date and time denoting the generation of response ISO 8601 format - YYYY-MM-DDTHH:MM:SS	String
BalanceEnquiryInfo	Tag carrying information on account balance	Object
AvailableBalance	Value representing the available balance in the account in their default currency	String

Error codes

Balance Enquiry uses two error-code categories:

ERRXXXX — Errors returned by the bank
MW-XXX — Errors generated by the SingleView validation system

Error Code	Description
`ERR0001`	Timeout! Unable to get response from the bank. Please try again or contact SingleView support if issue persists.
`ERR0002`	Invalid company code.
`ERR0003`	Company is not authorized to access this service.
`ERR0004`	Invalid or missing account number.
`ERR0005`	Invalid/missing TransactionType.
`ERR0006`	Invalid request format.
`ERR0007`	Request rate limit exceeded.
`ERR0008`	Account Number is not Registered.
`ERRXXXX`	Other scenarios to be handled and error codes to be released soon.
`MW-400`	Invalid BankCode.
`MW-XXX`	Other scenarios to be handled and error codes to be released soon.

Categories

GENERAL INFORMATION

GETTING STARTED

AUTHENTICATION

Data APIs

Payment APIs

SADAD

Virtual Accounts

SME Onboarding (Draft)

RESOURCES

API Archives

Balance enquiry (V2 - Draft)

Get balance enquiry

Endpoint details

Sample request

Sample responses

Error codes

Categories

GENERAL INFORMATION

GETTING STARTED

AUTHENTICATION

Data APIs

Payment APIs

SADAD

Virtual Accounts

SME Onboarding (Draft)

RESOURCES

API Archives

Get balance enquiry Endpoint details

Sample request

Sample responses

Error codes

Get balance enquiry

Endpoint details