Wallet - OLIVE Payment Platform

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

Type	Description	Direction
`transfer_p2p`	Person to person transfer	Debit/Credit
`agent_cashin`	Cash deposit via agent	Credit
`agent_cashout`	Cash withdrawal via agent	Debit
`pos_payment`	POS terminal purchase	Debit
`vult_fund`	Funding from VULT	Credit
`vult_transfer`	Transfer to VULT	Debit
`fee`	Transaction fee	Debit
`reversal`	Transaction reversal	Credit/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

Initiate Transfer

Sender provides recipient card serial, amount, and PIN

Validation

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

Execute Transfer

Atomic operation:

Debit sender (amount + fee)
Credit recipient (amount)
Record fee

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

Send Money to Friend

Get recipient’s card serial number
Call POST /api/v1/wallet/transfer-p2p
Include sender ID, recipient card, amount, PIN
Both parties receive WhatsApp notifications

Check Balance

Call POST /api/v1/wallet/balance/{subscriber_id}
Include PIN in request body
Returns current balance and currency

View Transaction History

Call POST /api/v1/wallet/transactions/{subscriber_id}
Include PIN, limit, and offset
Returns paginated transaction list

Generate Statement

Call POST /api/v1/wallet/account-statement
Specify date range and format (PDF/CSV)
Returns download URL for statement file

Fees

Transaction fees are configured per transaction type. See Fee Settings for configuration.

Transaction	Default Fee
P2P Transfer	1.5% (sender)
Agent Cash-In	0.5% (agent)
POS Payment	1.0% (processor)
VULT Fund	0%

Agent Cash-In

Deposit cash through agent

POS Payment

Pay at merchant terminal

Upload Cards CSV

Get Balance

​Key Features

Real-Time Balance

P2P Transfers

Transaction History

​Endpoints

Get Balance

Transactions

P2P Transfer

Internal Transfer

Fund from VULT

Account Statement

​Transaction Types

​Transaction Object

​Transfer Flow

​Balance Security

PIN Required

Rate Limited

​Common Workflows

​Fees

​Related

Agent Cash-In

POS Payment

Key Features

Endpoints

Transaction Types

Transaction Object

Transfer Flow

Balance Security

Common Workflows

Fees

Related