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"
}
{
"success": false,
"error": "Invalid PIN",
"attempts_remaining": 2
}
{
"error": "Subscriber not found",
"code": "SUBSCRIBER_NOT_FOUND"
}
Wallet
Get Balance
Get current wallet balance for a subscriber
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"
}
{
"success": false,
"error": "Invalid PIN",
"attempts_remaining": 2
}
{
"error": "Subscriber not found",
"code": "SUBSCRIBER_NOT_FOUND"
}
Balance queries require PIN verification to ensure only authorized users can view account balances.
Request
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)Path Parameters
string
required
Subscriber UUID (e.g.,
sub_abc123)Body Parameters
string
required
Subscriber’s 4-digit PIN for verification
Response
boolean
Whether query succeeded
integer
Current balance in cents
string
Formatted balance (e.g.,
125,000.00 SLE)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"
}
{
"success": false,
"error": "Invalid PIN",
"attempts_remaining": 2
}
{
"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 |
Authorizations
ApiKeyAuthBearerAuth
API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'
Path Parameters
Subscriber ID
Body
application/json
PIN for verification
Example:
"1234"
Response
Balance retrieved
The response is of type object.
⌘I