Get Wallet Balance API
The Get Wallet Balance API retrieves the balance of a specific wallet. It requires the walletId as a path parameter.
Endpoint
GET: {{baseURL}}/v1/wallet/{{walletId}}/balance
Note: Replace {{walletId}} with the actual wallet ID you got from the GET Wallet endpoint.
Request Example (cURL)
curl --location --request GET '{{baseURL}}/v1/wallet/{walletId}/balance' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json'Request Headers
| Header | Type | Description | Required | Example Value |
|---|---|---|---|---|
| x-api-key | String | API key for authentication | ✅ Yes | API_KEY_HERE |
| Content-Type | String | Request content type (JSON) | ✅ Yes | application/json |
Query Parameters
| Parameter | Type | Description | Required | Example Value |
|---|---|---|---|---|
| walletId | String | Unique identifier for wallet | ✅ Yes | 12345-xyz |
Success Response (200 OK)
{
"message": "wallet balance fetched successfully",
"status": "success",
"data": {
"id": "739d7131-d523-49ui-8524-xxxxxxxxxx",
"balance": 2300000000.00 ,
"currency": "NGN",
"country": "NG"
}
}Response Breakdown
| Field | Type | Description |
|---|---|---|
| id | String | The unique wallet identifier |
| balance | Number | Available balance in the wallet |
| currency | String | Currency of the balance |
| country | String | Country of currency |
Error Responses
| Status Code | Meaning | Example Response | How to Handle |
|---|---|---|---|
| 400 | Bad Request (Missing or Invalid walletId) | walletId is required | Ensure the request includes a valid walletId as a path or query parameter. |
| 401 | Unauthorized (Invalid API Key) | Invalid authentication credentials | Check that the x-api-key header is present and the key is valid. |
| 403 | Forbidden (Non-whitelisted IP) | Your IP address is not allowed to access this service | Add your IP to the allowed list in the API Management section of the Dashboard. |
| 404 | Wallet Not Found | Wallet with given ID not found | Confirm the walletId exists and belongs to your business account. |
| 422 | Unprocessable Entity | Invalid wallet format or unexpected value | Check if the walletId has correct format and that any additional parameters are valid. |
| 429 | Too Many Requests | API rate limit exceed | Implement retry logic with backoff; do not exceed allowed number of requests per second. |
| 500 | Internal Server Error | An unexpected error occurred on the server | Retry the request after some time or contact support if issue persists. |
| Internal Server Error | { "message": "Server failed to process request" } |