Balance Enquiry

• Method: POST
• Endpoint: /api/v1/balance-enquiry

Request Parameters

Request Parameters

Field Name	Data Type	Required	Description
requestId	String	Yes	Unique identifier generated by the originating institution to uniquely reference the balance enquiry request across the switch and participating banks.
stan	String	Yes	System Trace Audit Number assigned to the request for transaction tracking, reconciliation, and audit purposes.
processingCode	String	Yes	Code indicating the transaction type being requested. For balance enquiries, this value is defined by the switch processing code catalog.
tranDateTime	String (ISO-8601)	Yes	Date and time the balance enquiry was initiated by the source institution.
accountNumber	String	Yes	Account number for which the balance information is being requested.
currency	String	Yes	ISO 4217 currency code of the account to ensure correct balance representation.
countryCode	String	No	ISO 3166-1 alpha-2 country code indicating the origin of the balance enquiry transaction.
sourceInstitution	String	Yes	Code identifying the originating institution
channel	String	Yes	Transaction channel (API, WEB, MOBILE, POS)

Response Parameters

Response Parameters

Field Name	Data Type	Required	Description
requestId	String	Yes	Unique identifier of the original balance enquiry request, used for correlation and reconciliation across the switch and participating banks.
responseCode	String	Yes	Standard response code indicating the outcome of the balance enquiry request, as defined in the switch response code catalog (e.g., 00 = Successful).
responseMessage	String	Yes	Descriptive message corresponding to the response code, provided for logging, monitoring, and diagnostic purposes.
stan	String	Yes	System Trace Audit Number associated with the balance enquiry transaction, used for audit, tracking, and dispute resolution.
availableBalance	String	Optional	Current available balance on the requested account, representing the amount accessible for withdrawal or transfer at the time of enquiry.
ledgerBalance	String	Optional	Current ledger (book) balance on the requested account, including uncleared or pending transactions.
currency	String	YES	ISO 4217 currency code in which the balances are maintained (e.g., NGN).

Sample Request

Request Parameters

{
  "requestId": "REQ-20260123-000002",
  "stan": "000201",
  "processingCode": "310000",
  "tranDateTime": "2026-01-23T10:50:00",
  "accountNumber": "0000918480",
  "sourceInstitution": "044",
  "channel": "Mobile",
  "currency": "NGN",
  "countryCode": "NG"
}

Sample Response

Response Parameters

{
  "requestId": "REQ-20260123-000002",
  "responseCode": "00",
  "responseMessage": "SUCCESS",
  "stan": "000201",
  "availableBalance": "500000.00",
  "ledgerBalance": "600000.00",
  "currency": "NGN"
}