Get Balance - OLIVE Payment Platform

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

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

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

string

required

Example:

"1234"

Response

Balance retrieved

The response is of type object.

Wallet

Transaction History

​Request

​Path Parameters

​Body Parameters

​Response

​Examples

​Security

PIN Required

Attempt Limits

​Errors

Authorizations

Path Parameters

Body

Response

Request

Path Parameters

Body Parameters

Response

Examples

Security

Errors