Wallet services are no longer just a fintech feature — they've become a foundational layer across industries. From ride-hailing and e-commerce to travel and lifestyle platforms, businesses use wallets to streamline payments, store user balances, and deliver flexible financial experiences. Whether you're building a savings app, a lending platform, or a marketplace, integrating a wallet system allows you to manage customer funds securely and efficiently.
Monnify makes it easy to implement wallet functionality using its Customer Reserved Account API (for deposits) and Disbursement API (for withdrawals).
In this article, we'll walk through how to build a basic wallet service using Monnify, the key APIs you'll need, and best practices for ensuring your system is robust and secure.
What You'll Need
- An Account on Monnify: Sign up at app.monnify.com/create-account. Navigate to Developer > API Keys & Contracts to retrieve: API Key, Secret Key, Contract Code, and Wallet Account Number.
- Customer Reserved Account API: For assigning dedicated virtual accounts to customers so they can fund their wallets.
- Disbursement API: For initiating withdrawals directly to customers' bank accounts.
Wallet System Architecture Overview
The wallet system consists of two key flows: Deposits (via virtual accounts) and Withdrawals (via bank accounts).
Customer Reserved Accounts
Each customer gets a unique virtual account number (e.g., 6123456789). When they fund this account, Monnify notifies your system, and you credit the customer's wallet balance.
Disbursement API
When a customer requests a withdrawal, your system debits their wallet balance and uses the Disbursement API to transfer funds directly to their bank account.
Sample Transaction Flow
- Customer A signs up and is assigned a reserved account.
- They transfer ₦10,000 to their virtual account.
- Monnify sends a webhook to your backend notifying you of the deposit.
- Your system credits Customer A's wallet balance.
- Later, Customer A requests a ₦5,000 withdrawal.
- You debit the wallet and initiate a disbursement via Monnify.
- Monnify processes the transaction and returns a status update.
How Deposits Work
- On signup, call the Create Reserved Account API. Include the customer's BVN or NIN. This is mandatory for compliance.
- When a transfer hits the virtual account, Monnify sends a webhook notification.
- Validate the incoming webhook: Check the IP address (only allow Monnify's known IPs), compute and verify the monnify-signature, and confirm the account reference and amount.
- Credit the customer's wallet balance.
- Log the transaction and return a success response.
How Withdrawals Work
- The customer initiates a withdrawal request.
- Your system verifies the wallet has sufficient balance.
- Debit the wallet.
- Initiate a disbursement using the Disbursement API.
- Track the transaction status via API response, Webhook, and periodic reconciliation.
Pro Tips for a Smooth System
- Use unique references: For every withdrawal to prevent duplicates.
- Cache the customer's reserved account details.
- Validate webhook IPs: Only process Monnify-initiated callbacks.
- Make webhook handlers idempotent: Handle retries gracefully.
- Implement error handling: For failed or pending transactions.
- Reconcile regularly: Cross-check wallet balances with transaction logs.
- Secure PII: Especially BVNs, account numbers, and NINs.
- Lock during balance updates: To prevent race conditions in concurrent withdrawals.
- Test in sandbox: Simulate deposits and disbursements before going live.
Notes for Engineers
- This guide is language-agnostic, so you need to adapt it to your stack (Spring Boot, Laravel, Node.js, etc.).
- The flow is always: Validate the request → Process the business logic → Record the transaction → Update balances.
- Ensure atomicity: a failed disbursement should roll back any wallet deductions.
- Logs and metrics matter for audit trails and debugging.
In Summary
Building a wallet system with Monnify is straightforward when you understand the architecture and transaction flow. With proper implementation of virtual accounts, webhook handling, and disbursement logic, you can offer customers a smooth wallet experience that is secure, auditable, and scalable.
You can check out a Spring Boot implementation of the Monnify Wallet at: https://github.com/Monnify/monnify-wallet-impl-java
