Skip to main content

Overview

The Withdrawal System enables instructors and consultants to transfer their earned funds from their Learnille wallet to their external bank accounts. The system is designed with security, compliance, and reliability as core priorities.

Key Participants

High-Level Flow

Withdrawal Lifecycle

Status Flow

A withdrawal only leaves PROCESSING when Flutterwave reports a final transfer status: SUCCESSFUL → COMPLETED, FAILED or CANCELLED → FAILED. NEW and PENDING are ignored until the transfer finishes.

Process Details

1. Withdrawal Request Initiation

When a user requests a withdrawal, the system performs the following validations:
  • Balance Check: User must have sufficient available balance
  • KYC Verification: User must have completed identity verification
  • Method Verification: Selected bank account must be verified
  • Concurrent Limit: Maximum 3 pending withdrawals allowed per user
  • System Status: Global withdrawals must not be suspended

2. Two-Factor Approval

For security, withdrawals require OTP verification:
  1. System sends a 6-digit code to user’s registered email
  2. User enters the code to confirm the withdrawal
  3. Code expires after a configurable time period

3. Admin Review

All withdrawal requests go through manual admin review to:
  • Verify the request legitimacy
  • Check for suspicious activity patterns
  • Ensure compliance with platform policies
  • Prevent fraud and money laundering
Admins can:
  • Approve: Proceed with payout
  • Reject: Decline with reason
  • Request Info: Ask user for additional verification

4. Payout Processing

Once approved, the system:
  1. Deducts funds from user’s wallet (creates ledger entry)
  2. Queues the payout job for processing
  3. Initiates transfer via payment gateway
Transfer Types:
  • Instant: Immediate transfer to bank
  • Scheduled: Delayed transfer (default: 3-hour delay for fraud prevention)

5. Bank Transfer

The payment gateway (Flutterwave) handles:
  • Currency conversion (if applicable)
  • Bank routing and transfer
  • Status updates via webhooks (POST /payment/flutterwave-webhook). v3 sends transfer.completed; v4 sends other transfer.* events signed with flutterwave-signature. Both are handled, and the result is read from the transfer’s status.

6. Completion & Notifications

Users receive notifications at key stages:
  • Request submitted
  • Admin approval/rejection
  • Transfer completed/failed

Security Measures

Withdrawal Methods

Users must set up and verify a withdrawal method before requesting funds:
  1. Add Bank Account: User provides bank details (account number, bank name)
  2. Verification: System creates a recipient profile with payment gateway
  3. Activation: Once verified, the method can be used for withdrawals
Supported account types vary by country and payment gateway capabilities.

System Configuration

Integration Points

Monitoring & Audit

All withdrawal activities are logged for:
  • Compliance and regulatory requirements
  • Dispute resolution
  • Fraud detection and pattern analysis
  • System performance monitoring
Key metrics tracked:
  • Average processing time
  • Success/failure rates
  • Admin review turnaround time
  • Gateway response times

Error Handling

Future Considerations

  • Additional payment gateways for broader coverage
  • Automated approval for low-risk, verified users
  • Real-time balance updates during processing
  • Multi-currency wallet support