Payments

The Keshless User App supports various payment types including airtime purchases, bill payments, vendor payments, top-ups, and cash withdrawals.

Payment Types

Type	Description	Fee
Airtime	Mobile airtime purchase	Free
Bills	Utility and service bills	Varies
Vendor	Pay merchants	Free
Top-up	Add funds to wallet	Free
Withdraw	Cash out at agent	2%

Airtime Purchase

Flow

┌─────────────────┐
│  Select Network │
│  (MTN/Eswatini) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Enter Phone    │
│  (Self/Other)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Select Amount  │
│  or Enter Custom│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Confirm & Pay  │
│  (Enter PIN)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Success        │
│  (Show Voucher) │
└─────────────────┘

Supported Networks

Network	Code	Prefix
MTN Eswatini	mtn_sz	76, 78
Eswatini Mobile	esw_mobile	79

Airtime Amounts

• Quick amounts: E5, E10, E20, E50, E100, E200
• Custom amounts: E2 - E1000

Bill Payments

Supported Billers

Category	Billers
Electricity	ESWADE, SEC
Water	Eswatini Water
Internet	SwaziNet, MTN
TV	DStv, GOtv
Insurance	Old Mutual, Momentum

Bill Payment Flow

┌─────────────────┐
│  Select Biller  │
│  Category       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Select Service │
│  Provider       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Enter Account  │
│  Number         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Enter Amount   │
│  (or fetch)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Confirm & Pay  │
│  (Enter PIN)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Success        │
│  (Payment Ref)  │
└─────────────────┘

Bill Payment Request Fields

Field	Type	Required	Description
billerId	string	Yes	Biller ID
accountNumber	string	Yes	Account number
amount	number	Yes	Payment amount
reference	string	No	Optional reference

Vendor Payments

Pay via QR Code

1. Scan vendor's QR code
2. Enter amount (if not pre-set)
3. Confirm vendor name
4. Enter PIN
5. Complete payment

Pay via Merchant Code

1. Enter merchant code (6-digit)
2. Enter amount
3. Confirm vendor details
4. Enter PIN
5. Complete payment

Top-up Wallet

Top-up Methods

Method	Processing	Fee
Bank Transfer	1-24 hours	Free
Mobile Money	Instant	Free
Agent Cash	Instant	Free
Card	Instant	2.5%

Bank Transfer

1. View Keshless bank details
2. Transfer from your bank
3. Reference: Your phone number
4. Funds credited after confirmation

Agent Top-up

1. Visit Keshless agent
2. Provide phone number
3. Give cash to agent
4. Receive SMS confirmation

Cash Withdrawal

Withdrawal Flow

┌─────────────────┐
│  Enter Amount   │
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Find Agent     │
│  (Map/List)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Generate Code  │
│  (6-digit)      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Visit Agent    │
│  Give Code      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Receive Cash   │
│                 │
└─────────────────┘

Withdrawal Limits

KYC Level	Daily Limit	Per Transaction
Basic	E500	E200
Standard	E5,000	E2,000
Premium	E20,000	E10,000

API Endpoints

Endpoint	Method	Description
/payments/airtime	POST	Purchase airtime
/payments/bills	POST	Pay bill
/payments/vendor	POST	Pay vendor
/wallet/topup	GET	Get top-up options
/wallet/withdraw	POST	Generate withdrawal code

Error Handling

Error	Cause	Action
PAY_001	Insufficient balance	Top-up wallet
PAY_002	Invalid account	Verify account number
PAY_003	Biller unavailable	Try later
PAY_004	Amount too low	Check minimum
PAY_005	Transaction limit	Check limits

Related Files

File	Purpose
lib/screens/payments/airtime_screen.dart	Airtime
lib/screens/payments/bills_screen.dart	Bills
lib/screens/payments/vendor_payment_screen.dart	Vendor payments
lib/screens/payments/topup_screen.dart	Top-up
lib/screens/payments/withdraw_screen.dart	Withdraw
lib/controllers/payment_controller.dart	Payment controller
lib/services/payment_service.dart	Payment service