Skip to main content
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