Skip to content

Wallet & Payment Services Module

Overview

The Wallet module provides digital wallet management, e-money services, payment processing, and account reconciliation. It enables customers to store funds, transfer money, make payments, and manage multiple linked accounts.

API Prefix: /api/v1/wallet

Route Verification Status

  • Source Router: app/api/v1/endpoints/wallet.py
  • Live Route Count: 72
  • Verification State: Verified (2026-06-28)
  • Canonical Tracking: API_ROUTE_DOCUMENTATION_TODO.md
  • Verification Method: Route decorators extracted from @r.<method>(...) in app/api/v1/endpoints/wallet.py.

Key Features

1. Wallet Management

  • Create and manage digital wallets per customer
  • Multi-wallet per customer support
  • Wallet status tracking (Active, Frozen, Dormant, Closed)
  • KYC verification workflows
  • Wallet tier management based on KYC level

2. E-Money Products

  • Define e-money wallet products
  • Configure product features and limits
  • Product lifecycle management (Staging, Active, Declined, Disposed)
  • Product assignment to wallets
  • Default product designation

3. Wallet Operations

  • View wallet balance and transaction history
  • Freeze/unfreeze wallets
  • Update wallet status
  • Link bank accounts to wallet
  • Manage linked account defaults

4. Payment Processing

  • Wallet-to-wallet transfers
  • P2P payments with QR codes
  • Payment requests via QR code
  • Merchant payments
  • Transaction validation and execution
  • Transaction reversal for failed payments

5. Balance Management

  • Track balances per currency
  • Multi-currency support
  • Balance reconciliation
  • Currency addition to wallet
  • Ledger entries for transaction history

6. Limits & Controls

  • Set transaction limits by wallet tier
  • Temporary limit adjustments (daily, weekly, monthly)
  • KYC-based limit overrides
  • Limit audit trails
  • Velocity checks

7. KYC & Verification

  • KYC status tracking
  • KYC verification workflows
  • KYC limit adjustments
  • Customer tier management
  • Verification history

8. Security & PIN Management

  • Wallet PIN setup and management
  • PIN change and reset
  • PIN validation on transactions
  • Account lock after failed PIN attempts

9. Linked Accounts

  • Add bank accounts to wallet
  • Link to external accounts
  • Verify linked accounts
  • Set primary linked account
  • Remove linked accounts
  • Account ownership verification

10. QR Code Management

  • Generate P2P payment QR codes
  • Generate merchant payment QR codes
  • Generate payment request QR codes
  • QR code scanning and validation
  • QR code deactivation
  • QR code tracking and analytics

11. Reporting & Analytics

  • Wallet dashboard metrics
  • Transaction analytics
  • Top performers analytics
  • Distribution reports
  • Trends analysis
  • Fee reports
  • Statement generation and export

12. Account Reconciliation

  • Reconcile wallet balances
  • Reconciliation history tracking
  • Reconciliation summary reports
  • Discrepancy detection
  • Automatic reconciliation

API Endpoints (Verified Against Live Router)

For the complete wallet endpoint inventory (all 72 routes with method, effective path, and source line), use: - API_ROUTE_LIVE_REFERENCE.md -> section wallet.py (72 routes)

This document focuses on workflow and domain behavior. The live reference above is the canonical endpoint parity source.

Permission Dependency Notes (Verified)

Wallet routes are permission-gated across lifecycle, balance, payment, reconciliation, analytics, and product operations. Confirmed permission families in wallet.py include: - Wallet lifecycle: create_wallet, read_wallet, update_wallet, freeze_wallet. - Money movement: topup_wallet, transfer_wallet, withdraw_wallet, reverse_transaction, adjust_balance. - KYC and controls: verify_wallet_kyc, reconcile_wallet_balance. - Linked accounts and QR: manage_linked_accounts, generate_qr_codes, process_qr_payments. - Analytics and reporting: view_wallet_analytics, view_fee_reports, view_reconciliation_reports. - PIN security: set_wallet_pin, change_wallet_pin, reset_wallet_pin. - Product governance: create_wallet_product, update_wallet_product, stage_wallet_product, decline_wallet_product, dispose_wallet_product, view_wallet_product, delete_wallet_product, list_wallet_products, set_default_wallet_product, assign_wallets_to_product.

Operational note: - One product route currently uses an empty permission placeholder (permission_required("")) and should be made explicit.

Standard Error Response Matrix

Use this error contract shape for wallet flows:

{
   "status_code": 400,
   "error_code": "WALLET_ERROR",
   "message": "Human-readable summary",
   "details": {}
}

Common wallet error mappings: - 400 -> business rule failure (insufficient balance, invalid wallet state, limit violation). - 401 -> authentication failure. - 403 -> missing permission for wallet operation. - 404 -> wallet/linked-account/QR/resource not found. - 409 -> conflicting state transition or duplicate operation. - 422 -> schema validation failure. - 429 -> throttling/rate limit. - 500 -> internal processing or integration failure.

Database Models

Core Wallet Models

  • Wallet: User's digital wallet with balance tracking
  • WalletProduct: E-money product definition
  • WalletBalance: Multi-currency balance tracking
  • WalletTransaction: Transaction record (transfer, payment, withdrawal)
  • WalletLedger: Ledger entries for accounting

Linked Accounts

  • LinkedAccount: Bank or external account linked to wallet
  • LinkedAccountVerification: Verification status and history

Configuration & Controls

  • WalletLimit: Transaction limits by wallet/product/tier
  • TemporaryLimitAdjustment: Temporary limit overrides
  • WalletFreezeRecord: Track wallet freezes and unfreezes
  • WalletPin: Encrypted PIN storage
  • WalletKYC: KYC status and tier information

QR Code Management

  • QRCode: QR code generation and tracking
  • QRCodeTransaction: Link QR codes to transactions
  • QRCodeMetadata: QR code configuration and type

Reconciliation

  • WalletReconciliation: Reconciliation records
  • ReconciliationDiscrepancy: Track balance discrepancies

Reporting

  • WalletStatement: Statement records for audit trail
  • WalletAnalytics: Pre-calculated analytics data

Wallet Lifecycle

Customer Wallet Onboarding

1. Customer Registration
   ├─ Register with phone/email
   ├─ Set password
   └─ Create basic profile

2. KYC Verification
   ├─ Provide ID and proof of address
   ├─ System verifies documents
   ├─ Customer assigned KYC tier
   └─ Limits set based on KYC level

3. Wallet Creation
   ├─ Select wallet product
   ├─ Set PIN
   ├─ Provide initial information
   └─ Wallet activated

4. Account Linking (Optional)
   ├─ Customer links bank account
   ├─ Micro-deposit verification
   ├─ Account confirmed
   └─ Available for transfers

Payment Flow

1. Initiate Payment
   ├─ Select transaction type (P2P, Merchant, Withdrawal)
   ├─ Enter amount and recipient
   ├─ System validates transaction
   └─ Generate payment request

2. Authenticate
   ├─ PIN validation
   ├─ OTP verification (if enabled)
   └─ Biometric validation (if enabled)

3. Process Payment
   ├─ Debit source wallet
   ├─ Apply fees
   ├─ Credit destination
   ├─ Record transaction
   └─ Generate receipt

4. Notification
   ├─ Notify sender
   ├─ Notify recipient
   └─ Send confirmation receipts

KYC & Wallet Tiers

Tier 1: Basic

  • Max balance: 10,000
  • Max daily transaction: 5,000
  • Max monthly transactions: 50,000
  • KYC: Phone number verification

Tier 2: Standard

  • Max balance: 50,000
  • Max daily transaction: 25,000
  • Max monthly transactions: 250,000
  • KYC: ID verification + address

Tier 3: Premium

  • Max balance: 500,000
  • Max daily transaction: 250,000
  • Max monthly transactions: 2,500,000
  • KYC: Full KYC + income verification

Tier 4: Business

  • Unlimited balance
  • Unlimited transactions
  • Batch payment capability
  • KYC: Business registration + beneficial owner verification

Controllers & Business Logic

Key Controllers

  • controller/wallet.py: Wallet operations
  • create_wallet(): Create new wallet
  • process_transfer(): Execute wallet transfer
  • process_payment(): Process payment
  • apply_transaction_fees(): Calculate and apply fees

  • validate_transaction(): Pre-transaction validation

  • controller/wallet_product.py: Product management

  • create_product(): Create product
  • assign_product(): Assign to wallets

  • manage_product_lifecycle(): Stage, activate, dispose

  • controller/wallet_kyc.py: KYC management

  • verify_kyc(): Verify customer documents
  • assign_tier(): Assign KYC tier

  • update_limits(): Update based on tier

  • controller/wallet_reconciliation.py: Reconciliation

  • reconcile_balance(): Verify and reconcile
  • detect_discrepancies(): Find balance issues

  • generate_reconciliation_report(): Create reports

  • controller/qr_code.py: QR code management

  • generate_qr_code(): Create QR payload
  • scan_qr_code(): Validate scanned code
  • process_qr_payment(): Execute QR-based payment

Configuration

Wallet Product Configuration

{
  "name": "Standard Wallet",
  "currency": "ZMW",
  "min_balance": 0,
  "max_balance": 100000,
  "transaction_fee_percent": 1.5,
  "daily_limit": 50000,
  "monthly_limit": 500000,
  "kyc_tier_required": 2,
  "features": ["p2p_transfer", "bill_payment", "merchant_payment"],
  "active": true
}

Limit Configuration

{
  "tier": "basic",
  "daily_transaction_limit": 5000,
  "daily_count_limit": 10,
  "monthly_transaction_limit": 50000,
  "balance_limit": 10000,
  "can_link_accounts": false,
  "can_merchant_payment": false
}

Transaction Types

1. P2P Transfer

  • Send money to another wallet user
  • Recipient identified by phone/email/wallet ID
  • Sender and recipient both have accounts

2. Merchant Payment

  • Pay merchant/business
  • Merchant identified by merchant ID or phone
  • Optional invoice/reference

3. Bill Payment

  • Pay utility/service bills
  • Biller ID and bill reference required
  • Pre-defined billers in system

4. Cash Withdrawal

  • Withdraw to linked bank account
  • Immediate or scheduled
  • Withdrawal fee applies

5. Cash Deposit

  • Deposit to wallet via linked account
  • Manual or automatic
  • Deposit fee may apply

6. QR Code Payment

  • Scan merchant QR code for payment
  • Scan payment request for receivable
  • Dynamic or static QR codes

Fee Structure

Common Fees

P2P Transfer: 1% (min 50, max 500)
Merchant Payment: 1.5% (min 100, max 2000)
Bill Payment: 0.5% (min 25, max 300)
Cash Withdrawal: 2% (min 200, max 5000)
Cash Deposit: 0.25%
Wallet Creation: Free
Card Issuance: 500 (one-time)

Integration Points

External Services

  • Bank Connections: Link bank accounts via APIs
  • Merchant Gateways: Process merchant payments
  • Bill Aggregators: Connect to utility providers
  • Notification System: SMS/Email transaction alerts
  • Reporting System: Generate financial statements

Internal Modules

  • Authentication: Verify wallet owner
  • Transaction Processing: Record transactions
  • Customer Management: Access customer data
  • Campaign Management: Apply wallet promotions
  • Policy Management: Enforce limits and controls
  • Audit Logging: Track all operations

Security Features

  1. PIN Management: Encrypted PIN storage
  2. Transaction Verification: PIN + OTP for high-value transactions
  3. Device Binding: Optional device fingerprinting
  4. Geofencing: Location-based transaction controls
  5. Rate Limiting: Velocity checks on transactions
  6. Fraud Detection: Unusual pattern detection
  7. Audit Trail: Complete transaction history
  8. Account Freezing: Quick account lockdown capability

Error Handling

Common Errors

  • INSUFFICIENT_BALANCE: Not enough funds
  • LIMIT_EXCEEDED: Daily/monthly limit exceeded
  • INVALID_RECIPIENT: Recipient not found or invalid
  • INVALID_PIN: PIN mismatch
  • WALLET_FROZEN: Wallet is frozen
  • KYC_REQUIRED: Customer must complete KYC
  • INVALID_AMOUNT: Amount outside allowed range
  • TRANSACTION_FAILED: Transaction failed to process

Testing

Test Categories

  • Wallet creation and KYC workflows
  • Transaction processing (P2P, merchant, cash)
  • Balance updates and reconciliation
  • QR code generation and scanning
  • PIN management and security
  • Limit enforcement

Test Files

  • tests/test_wallet.py: Wallet operations
  • conftest.py: Wallet test fixtures

Performance Considerations

  1. Balance Caching: Cache wallet balance in Redis
  2. Batch Reconciliation: Run reconciliation in background jobs
  3. Transaction Indexing: Index on wallet_id, transaction_date
  4. Statement Generation: Pre-generate for quick retrieval
  5. Analytics Aggregation: Pre-calculate metrics hourly