Wallet Balance

Retrieve the NGN wallet balance and available balance for a business.

Endpoint

GET /v1/auth/wallet/balance

Authentication

Pass your API key in the request header:

token: <your_api_key>

Response

{
  "success": true,
  "message": "Wallet balance retrieved successfully",
  "data": {
    "businessId": "64a1f...",
    "businessName": "Acme Ltd",
    "ledgerBalance": 5000,
    "availableBalance": 3800
  }
}

Fields

Field	Type	Description
ledgerBalance	number	Your official account balance. This is the settled NGN balance on record before any pending transactions.
availableBalance	number	The amount you can spend right now. Calculated as ledgerBalance minus the sum of all pending debit transactions.

Rate Limiting

This endpoint is limited to 2 requests per minute per business (keyed on your API token).

Exceeding the limit returns HTTP 429:

{
  "success": false,
  "message": "Too many requests, please try again after a minute."
}

Notes

• Both balances are in NGN (Nigerian Naira).
• availableBalance will be lower than ledgerBalance when there are pending debits.
• If no wallet exists for the business, both values return 0.