Wallet

The wallet is the core feature of the Keshless User App, providing users with balance management, money transfers, and transaction tracking.

Wallet Home

The main wallet screen displays:

• Balance Display: Current available balance
• Quick Actions: Send, Receive, Pay, Top-up
• Recent Transactions: Last 5 transactions
• Linked Cards: NFC cards associated with the account

Balance Management

Balance Types

Type	Description
Available	Funds ready for use
Pending	Incoming transfers being processed
Reserved	Funds held for pending payments

Balance Refresh

Balance updates automatically via:

• Pull-to-refresh gesture
• Background refresh every 30 seconds
• Push notifications for transactions

Send Money

Send Flow

┌─────────────────┐
│  Enter Amount   │
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│  Select Contact │────▶│  Enter Phone    │
│  or Enter Phone │     │   Manually      │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
            ┌─────────────────┐
            │  Add Note       │
            │  (Optional)     │
            └────────┬────────┘
                     │
                     ▼
            ┌─────────────────┐
            │  Confirm Details│
            │                 │
            └────────┬────────┘
                     │
                     ▼
            ┌─────────────────┐
            │  Enter PIN      │
            │                 │
            └────────┬────────┘
                     │
                     ▼
            ┌─────────────────┐
            │  Success        │
            │  (Share Receipt)│
            └─────────────────┘

Transfer Request Fields

Field	Type	Required	Description
recipientPhone	string	Yes	Recipient phone number
amount	number	Yes	Transfer amount
note	string	No	Optional note
currency	string	Auto	Always SZL

Fees

Transfer Type	Fee
To Keshless user	Free
To bank account	2% (min E5)
To mobile money	1.5% (min E3)

Receive Money

QR Code Generation

Users can receive money by sharing a QR code containing:

Field	Description
type	keshless_payment
recipient	User phone number
name	User full name
amount	Optional pre-set amount

QR Code Scanning

Scan another user's QR code to send money directly.

Transaction History

List View

Transactions are displayed with:

• Transaction type icon
• Recipient/sender name
• Amount (+ or -)
• Date and time
• Status indicator

Filtering Options

Filter	Options
Type	All, Sent, Received, Payments, Top-ups
Date Range	Today, Week, Month, Custom
Status	All, Completed, Pending, Failed

Pagination

Transactions load 20 at a time with infinite scroll.

Transaction Details

Each transaction shows:

• Full transaction ID
• Complete timestamp
• Amount and fee breakdown
• Recipient/sender details
• Transaction status
• Reference number
• Option to share receipt

API Endpoints

Endpoint	Method	Description
/wallet/balance	GET	Get current balance
/wallet/send	POST	Send money
/wallet/transactions	GET	List transactions
/wallet/transactions/:id	GET	Transaction details
/wallet/qr/generate	POST	Generate receive QR

Error Handling

Error	Cause	Action
WALLET_001	Insufficient funds	Show balance, suggest top-up
WALLET_002	Invalid recipient	Verify phone number
WALLET_003	Daily limit exceeded	Show limits, try tomorrow
WALLET_004	Transaction failed	Retry or contact support
WALLET_005	Account suspended	Contact support

Related Files

File	Purpose
lib/screens/wallet/wallet_home_screen.dart	Wallet home
lib/screens/wallet/send_money_screen.dart	Send money
lib/screens/wallet/receive_screen.dart	Receive
lib/screens/wallet/qr_scanner_screen.dart	QR scanner
lib/screens/transactions/transaction_list_screen.dart	Transaction list
lib/screens/transactions/transaction_detail_screen.dart	Transaction details
lib/controllers/wallet_controller.dart	Wallet controller
lib/controllers/transaction_controller.dart	Transaction controller
lib/services/wallet_service.dart	Wallet service