Balance Query API

Overview

The balance query API allows merchants to query account balance in real time. This is important for fund management, pre-transaction balance checks and financial reconciliation.

API Info

• Endpoint: GET /api/balance
• Method: GET
• Content-Type: application/json

Request Headers

All API requests require the following headers, see API Signature:

Header	Type	Required	Description
Content-Type	string	Y	application/json, fixed
MerchantId	string	Y	Merchant ID provided by Veloraya
Timestamp	string	Y	Current timestamp (ms), anti-replay
Nonce	string	Y	Random string, unique per request, anti-replay
Signature	string	Y	Request signature (RSA), Base64 encoded

Request Parameters

No request parameters; the merchant ID is passed via headers.

Response Format

All APIs use a unified JSON response format:

Field	Type	Description
code	int	200 success, non-200 failure
msg	string	Response message
data	object	Response data, contains balance on success

Response Parameters (data)

Field	Type	Description
availableBalance	BigDecimal	Available balance
unsettledAmount	BigDecimal	Unsettled amount
frozenAmount	BigDecimal	Frozen amount

Response Example

Success

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "availableBalance": 16569.88,
    "unsettledAmount": 0.00,
    "frozenAmount": 131.61
  }
}

Error Codes

See Error Codes for details.

Notes

• Headers: all required headers must be passed (Content-Type, MerchantId, Timestamp, Nonce, Signature), see API Signature
• Signature: all requests must include a valid signature