Financial System
Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-10-02
Version: v1.0
Base URL:
Short Description: The Financial System manages all monetary transactions using double-entry bookkeeping. It handles user wallets, escrow for secure payments, transaction tracking, and payment processing with complete auditability.
Core Components
1. Ledger System
Double-entry bookkeeping where every transaction has equal debits and credits. Maintains user wallets, escrow accounts, platform revenue, and external flow tracking.
2. Escrow Management
Holds buyer payments until delivery confirmation. Protects both parties and automatically splits funds: 95% to seller, 5% platform fee.
3. Transaction History
User-facing records of all financial activity including purchases, refunds, and wallet operations.
Payment Flow
- Validate checkout and payment method
- Move funds to escrow via ledger
- Create transaction records
- Generate order on success
- Release funds after delivery (seller 95%, platform 5%)
Payment Methods
Active: WALLET, CASH_ON_DELIVERY
Planned: Mobile money (M-Pesa, Tigo Pesa, Airtel Money), cards, bank transfers
Technical Specifications
- Currency: TZS (Tanzanian Shillings)
- Precision: BigDecimal (15 digits, 2 decimals)
- All operations are atomic transactions
- Complete audit trail maintained