Wallet

Info

The Wallet API provides core financial operations for SmartPay 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-p2p

Send money by card serial

Internal Transfer

POST /api/v1/wallet/transfer

Transfer between accounts

Fund from VULT

POST /api/v1/wallet/fund-from-vult

Top up from VULT wallet

Account Statement

POST /api/v1/wallet/account-statement

Generate 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

Warning

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

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

Check Balance

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

View Transaction History

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

Generate Statement

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.

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

---

Related

Agent Cash-In

Deposit cash through agent

POS Payment

Pay at merchant terminal