Withdrawal

Agents process cash withdrawals for users who want to convert their digital wallet balance to physical cash.

Overview

The withdrawal process involves:

1. Customer requests withdrawal via User App
2. Agent receives withdrawal code
3. Agent verifies and dispenses cash
4. Transaction completes

Withdrawal Methods

Method 1: Customer-Initiated (Code)

Customer generates a withdrawal code in User App:

User App                      Vendor App
─────────                    ───────────
Generate Code ──────────────▶ Enter Code
   E500                      Verify Code
   CODE: 847291         ────▶ Dispense Cash
                              Confirm

Method 2: Agent-Initiated (Direct)

Agent initiates withdrawal for customer:

Vendor App
───────────
Enter Phone ──▶ Find User ──▶ Enter Amount ──▶ User Approves (OTP) ──▶ Dispense

Code-Based Withdrawal

Step 1: Enter Code

Agent enters the 6-digit code provided by customer.

Field	Value
Code Length	6 digits
Validity	30 minutes
Usage	Single use only

Code Validation States

State	Description
Valid	Proceed to details
Expired	Code has expired
Used	Already processed
Invalid	Code not found

Step 2: Verify Details

System displays withdrawal details:

Field	Description
Customer Name	Full name
Phone	Customer phone
Withdrawal Amount	Total amount
Your Fee	Agent commission
Cash to Give	Amount to dispense
Expiry	Code expiration time

Step 3: Process Withdrawal

Agent confirms cash handover and completes transaction.

Confirmation: Agent must confirm they have given the cash to customer.

Direct Withdrawal

Agent-Initiated Flow

1. Find customer by phone number
2. Enter withdrawal amount (up to customer's balance)
3. System sends OTP to customer
4. Customer provides OTP to agent
5. Agent enters OTP to complete

Fee Structure

Amount Range	Customer Fee	Agent Commission
E10 - E500	E5	E2
E501 - E2,000	2%	1%
E2,001+	1.5%	0.75%

Limits

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

API Endpoints

Endpoint	Method	Description
/withdrawal/verify	GET	Verify withdrawal code
/withdrawal/complete	POST	Complete code withdrawal
/withdrawal/initiate	POST	Start direct withdrawal
/withdrawal/verify-otp	POST	Verify OTP & complete

Error Handling

Error	Cause	Action
WITH_001	Invalid code	Check code
WITH_002	Code expired	User generates new code
WITH_003	Already processed	Transaction complete
WITH_004	Insufficient balance	User has not enough
WITH_005	Agent limit reached	Try tomorrow

Related Files

File	Purpose
lib/screens/withdrawal/code_entry_screen.dart	Code entry
lib/screens/withdrawal/direct_withdrawal_screen.dart	Direct withdrawal
lib/screens/withdrawal/otp_verification_screen.dart	OTP verification
lib/screens/withdrawal/withdrawal_success_screen.dart	Success screen
lib/controllers/withdrawal_controller.dart	Withdrawal controller
lib/services/withdrawal_service.dart	Withdrawal service