Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt

Use this file to discover all available pages before exploring further.

The Wallet API provides core financial operations for OLIVE accounts. All monetary operations are atomic and recorded in the transaction ledger.

​
Key Features

Real-Time Balance

Instant balance queries with PIN verification

P2P Transfers

Send money to any subscriber by card

Transaction History

Complete audit trail of all operations

​
Endpoints

Get Balance

POST /api/v1/wallet/balance/{id}Get current wallet balance (PIN required)

Transactions

POST /api/v1/wallet/transactions/{id}Get transaction history

P2P Transfer

POST /api/v1/wallet/transfer-p2pSend money by card serial

Internal Transfer

POST /api/v1/wallet/transferTransfer between accounts

Fund from VULT

POST /api/v1/wallet/fund-from-vultTop up from VULT wallet

Account Statement

POST /api/v1/wallet/account-statementGenerate PDF/CSV statement

​
Transaction Types

TypeDescriptionDirection
transfer_p2pPerson to person transferDebit/Credit
agent_cashinCash deposit via agentCredit
agent_cashoutCash withdrawal via agentDebit
pos_paymentPOS terminal purchaseDebit
vult_fundFunding from VULTCredit
vult_transferTransfer to VULTDebit
feeTransaction feeDebit
reversalTransaction reversalCredit/Debit

​
Transaction Object

{
  "id": "txn_abc123",
  "type": "transfer_p2p",
  "status": "completed",
  "amount": 5000000,
  "amount_formatted": "50,000.00 SLE",
  "fee": 75000,
  "fee_formatted": "750.00 SLE",
  "currency": "SLE",
  "direction": "debit",
  "counterparty": {
    "id": "sub_xyz789",
    "name": "Jane Smith",
    "card_serial": "OLIV0002"
  },
  "balance_after": 12500000,
  "memo": "Payment for services",
  "created_at": "2025-01-15T10:30:00Z"
}

​
Transfer Flow

1

Initiate Transfer

Sender provides recipient card serial, amount, and PIN
2

Validation

  • Verify sender PIN
  • Check sender balance (amount + fee)
  • Validate recipient exists and is active
  • Run compliance checks
3

Execute Transfer

Atomic operation:
  • Debit sender (amount + fee)
  • Credit recipient (amount)
  • Record fee
4

Notification

Both parties receive WhatsApp confirmation

​
Balance Security

Balance queries require PIN verification to prevent unauthorized access.

PIN Required

All balance and history queries need 4-digit PIN

Rate Limited

Failed PIN attempts are tracked and limited

​
Common Workflows

  1. Get recipient’s card serial number
  2. Call POST /api/v1/wallet/transfer-p2p
  3. Include sender ID, recipient card, amount, PIN
  4. Both parties receive WhatsApp notifications
  1. Call POST /api/v1/wallet/balance/{subscriber_id}
  2. Include PIN in request body
  3. Returns current balance and currency
  1. Call POST /api/v1/wallet/transactions/{subscriber_id}
  2. Include PIN, limit, and offset
  3. Returns paginated transaction list
  1. Call POST /api/v1/wallet/account-statement
  2. Specify date range and format (PDF/CSV)
  3. Returns download URL for statement file

​
Fees

Transaction fees are configured per transaction type. See Fee Settings for configuration.
TransactionDefault Fee
P2P Transfer1.5% (sender)
Agent Cash-In0.5% (agent)
POS Payment1.0% (processor)
VULT Fund0%

Agent Cash-In

Deposit cash through agent

POS Payment

Pay at merchant terminal