Top-up

Agents can convert customer cash into digital wallet funds through the top-up feature.

Overview

The top-up flow allows agents to:

1. Receive cash from a customer
2. Add funds to the customer's Keshless wallet
3. Earn commission on each transaction

Top-up Flow

┌─────────────────────────────────────────────────────────┐
│                    Top-up Flow                           │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐│
│  │   Enter     │────▶│   Find      │────▶│   Confirm   ││
│  │   Phone     │     │   Customer  │     │   Details   ││
│  └─────────────┘     └─────────────┘     └──────┬──────┘│
│                                                  │       │
│                                                  ▼       │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐│
│  │   Receipt   │◀────│   Success   │◀────│   Enter     ││
│  │             │     │             │     │   Amount    ││
│  └─────────────┘     └─────────────┘     └─────────────┘│
│                                                          │
└─────────────────────────────────────────────────────────┘

Step 1: Find Customer

By Phone Number

1. Enter customer phone number
2. System validates and finds user
3. Display customer name for confirmation

By NFC Card

Alternatively, tap customer's card to identify them.

Step 2: Enter Amount

Agent enters the top-up amount.

Amount Validation

Rule	Value
Minimum	E10
Maximum	E5,000
Decimals	2 places

Fee Structure

Amount Range	Fee
E10 - E100	E1 flat
E101 - E1,000	1%
E1,001+	0.5% (max E50)

Step 3: Confirm & Process

Confirmation Screen

Field	Description
Customer	Customer name
Phone	Customer phone
Top-up Amount	Amount to add
Your Commission	Agent earnings
Cash to Collect	Amount from customer

Important: Ensure cash is collected before confirming.

Step 4: Success & Receipt

Receipt Options

Option	Description
Print	Bluetooth thermal printer
SMS	Send to customer phone
New	Start new top-up

Limits

Limit Type	Value
Min per transaction	E10
Max per transaction	E5,000
Daily per customer	E10,000
Daily per agent	E50,000

API Endpoints

Endpoint	Method	Description
/topup/lookup	GET	Find user by phone
/topup/lookup-card	GET	Find user by card
/topup/process	POST	Process top-up
/topup/limits	GET	Check current limits

Error Handling

Error	Cause	Action
TOP_001	User not found	Verify phone number
TOP_002	User not verified	Customer needs KYC
TOP_003	Customer limit reached	Check daily limits
TOP_004	Agent limit reached	Try tomorrow
TOP_005	Insufficient float	Top-up agent account

Related Files

File	Purpose
lib/screens/topup/customer_lookup_screen.dart	Customer lookup
lib/screens/topup/topup_amount_screen.dart	Amount entry
lib/screens/topup/topup_confirm_screen.dart	Confirmation
lib/screens/topup/topup_success_screen.dart	Success screen
lib/controllers/topup_controller.dart	Top-up controller
lib/services/topup_service.dart	Top-up service