Building a Wallet Service with Monnify

By Oreoluwa Somuyiwa 19th Oct, 2025

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.

Create a Monnify Account

Before you can start integrating to Monnify, you will need to create a Monnify account.

Create Account

What You’ll Need

An Account on Monnify:
If you haven't already, sign up for a Monnify account here Then, navigate to Developer > API Keys & Contracts to retrieve the following necessary API credentials:
- API Key
- Secret Key
- Contract Code
- 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)
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

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.

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:
1. Check the IP address (only allow Monnify’s known IPs).
2. Compute and verify the monnify-signature
3. 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:
1. API response,
2. Webhook,
3. 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:
1. Validate the request
2. Process the business logic
3. Record the transaction
4. 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.