Get Balance

POST/wallet/balance/{subscriber_id}Open in the API playground →

Info

Balance queries require PIN verification to ensure only authorized users can view account balances.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Path Parameters

subscriber_idstringpathrequired

Subscriber UUID (e.g., sub_abc123)

Body Parameters

pinstringbodyrequired

Subscriber's 4-digit PIN for verification

---

Response

successboolean

Whether query succeeded

balanceinteger

Current balance in cents

balance_formattedstring

Formatted balance (e.g., 125,000.00 SLE)

currencystring

Currency code (SLE)

---

Examples

Request

cURL

curl -X POST "https://demo.api.vultlocal.com/api/v1/wallet/balance/sub_abc123" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pin": "1234"
  }'

Response

200 Success

{
  "success": true,
  "balance": 12500000,
  "balance_formatted": "125,000.00 SLE",
  "currency": "SLE",
  "subscriber_id": "sub_abc123",
  "last_transaction_at": "2025-01-15T10:30:00Z"
}

401 Invalid PIN

{
  "success": false,
  "error": "Invalid PIN",
  "attempts_remaining": 2
}

404 Not Found

{
  "error": "Subscriber not found",
  "code": "SUBSCRIBER_NOT_FOUND"
}

---

Security

PIN Required

Every balance query requires PIN verification

Attempt Limits

3 failed attempts locks account for 30 minutes

---

Errors

Status	Code	Description
400	INVALID_PIN_FORMAT	PIN must be 4 digits
401	INVALID_PIN	PIN verification failed
401	UNAUTHORIZED	Invalid API key
403	ACCOUNT_LOCKED	Too many failed attempts
404	SUBSCRIBER_NOT_FOUND	Subscriber not found
500	INTERNAL_ERROR	Server error