Skip to main content
POST
/
wallet
/
balance
/
{subscriber_id}
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"
  }'

{
  "success": true,
  "balance": 12500000,
  "balance_formatted": "125,000.00 SLE",
  "currency": "SLE",
  "subscriber_id": "sub_abc123",
  "last_transaction_at": "2025-01-15T10:30:00Z"
}
Balance queries require PIN verification to ensure only authorized users can view account balances.

​
Request

​
Authorization
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)

​
Path Parameters

​
subscriber_id
string
required
Subscriber UUID (e.g., sub_abc123)

​
Body Parameters

​
pin
string
required
Subscriber’s 4-digit PIN for verification

​
Response

​
success
boolean
Whether query succeeded
​
balance
integer
Current balance in cents
​
balance_formatted
string
Formatted balance (e.g., 125,000.00 SLE)
​
currency
string
Currency code (SLE)

​
Examples

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"
  }'

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

​
Security

PIN Required

Every balance query requires PIN verification

Attempt Limits

3 failed attempts locks account for 30 minutes

​
Errors

StatusCodeDescription
400INVALID_PIN_FORMATPIN must be 4 digits
401INVALID_PINPIN verification failed
401UNAUTHORIZEDInvalid API key
403ACCOUNT_LOCKEDToo many failed attempts
404SUBSCRIBER_NOT_FOUNDSubscriber not found
500INTERNAL_ERRORServer error

Authorizations

​
Authorization
string
header
required

API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'

Path Parameters

​
subscriber_id
string
required

Subscriber ID

Body

application/json

PIN for verification

​
pin
string
required
Example:

"1234"

Response

Balance retrieved

The response is of type object.