Wallet Data Model: Ledger, Transactions, and Balances
The correct approach is a double-entry ledger system where every financial event creates a debit from one account and a credit to another. Core tables include wallets (one per user), transactions (every financial event with reference, type, amount in kobo, and status), and ledger entries (double-entry records linking transactions to wallets). Never store a user’s balance directly. Compute it from the ledger to prevent corruption. Each transaction needs a unique system-generated reference stored alongside the payment gateway reference.
Debit/Credit Architecture
Every transaction must be processed atomically using database transactions. A funding transaction creates a pending record, the gateway processes the charge, the webhook updates status to success, and ledger entries credit the user and debit the settlement account. For transfers, verify sufficient balance from the ledger, debit the sender and credit the receiver in a single database transaction. Atomicity prevents double-spending and lost funds.
Escrow Considerations
Escrow holds funds from the buyer until both parties confirm satisfaction. Implement a separate escrow ledger account. Debit the buyer and credit escrow on purchase. Debit escrow and credit the seller on confirmation. Implement configurable timeouts (7-14 days typical) for automatic fund release. Maintain audit trails for all escrow transactions including holds, releases, and reversals.
CBN Wallet Regulations
CBN regulates wallets through the Guidelines on Digital Banking and Technology Risk Assessment. Implement three KYC tiers. Level 1: basic info, ₦50,000 daily limit. Level 2: BVN/NIN, ₦200,000 daily. Level 3: physical address, ₦1,000,000+ daily. Register with NITDA for NDPR compliance. Retain transaction records for five years. See our CBN compliance checklist 2026 for details.
Development Cost Breakdown (N4M-N12M)
Basic wallet MVP with funding, transfers, and Paystack integration: ₦4M-₦8M. Full-featured platform with escrow, multi-currency, and compliance: ₦8M-₦12M. Cost breakdown: UI/UX 10-15% (₦400K-₦1.5M), backend including ledger and gateway integration 35-40% (₦1.4M-₦4.8M), mobile app 30-35% (₦1.2M-₦4.2M), compliance and security testing 10-15% (₦400K-₦1.8M). Legal fees for CBN licensing add ₦5M-₦10M.
Security Best Practices
Use bcrypt or Argon2 for password hashing. Rate limit logins to 5 attempts per minute per IP. Require PIN or biometric authentication for transactions. Implement session timeout after 15 minutes. Validate all API inputs with parameterised queries. TLS 1.2+ for all communications. AES-256 for data at rest. Comprehensive immutable audit logging retained for five years.
Frequently Asked Questions
How much does it cost to develop a wallet app in Nigeria?
A basic wallet app costs ₦4 million to ₦8 million. A full-featured platform with escrow, multi-currency, and compliance features ranges from ₦8 million to ₦12 million.
What database design is best for a wallet app?
Use a double-entry ledger system with PostgreSQL. Every credit has a corresponding debit. Compute balances from the ledger rather than storing them directly.
What CBN regulations apply to wallet apps?
Comply with CBN Guidelines on Digital Banking, Technology Risk Assessment framework, KYC verification, transaction limits by KYC level, and NDPR data protection.
How does escrow work in a wallet app?
Create a separate ledger account for held funds. Debit the buyer and credit escrow on purchase. Release to seller on confirmation or automatically after timeout.