Customers & Virtual Bank Accounts
The Customers API lets you onboard your end users as first-class customers, verify their identity with BVN, and issue each one a dedicated NGN virtual bank account (VBA). Deposits into a customer’s account are credited to a dedicated ledger wallet that you can query, pay out from, or sweep to your own wallet.
Use it to power:
- Neobank & wallet apps — every user gets a real, permanent NGN account number
- Marketplaces — collect seller or buyer funds into isolated per-customer balances
- Payroll & disbursement products — hold and pay out per-customer funds with full audit history
All customer endpoints require your secret key (LIVE;SK;...). Public keys are rejected. All create operations require an Idempotency-Key header — retrying with the same key safely replays the original response.
The Lifecycle
- Create a customer with your own
externalReference - Verify their identity (BVN) — required before an account can be issued
- Create a virtual bank account — a dedicated NGN account number plus a ledger wallet
- Receive deposits — credited automatically; you get a
customer.deposit.creditedwebhook - Check balances, pay out, or transfer — withdrawals to any bank, or internal transfers to your merchant wallet
What You Can Do
Virtual Bank Accounts
Create customers, run BVN verification, and issue dedicated NGN account numbers.
Deposits & Balances
Track credited deposits, query ledger balances, and list sanitized transaction history.
Withdrawals & Transfers
Pay out to any bank, preflight fees and limits, and move funds to your merchant wallet.
Key Concepts
| Concept | Meaning |
|---|---|
| Customer | Your end user, scoped to your app, identified by your externalReference |
| Identity verification | A BVN check that must be verified and eligible before a VBA can be created |
| Virtual bank account | A permanent SafeHaven NGN account number owned by one customer |
| Customer wallet | The platform ledger wallet behind each VBA — the authoritative balance |
| Sweep destination | Where deposited funds physically settle (platform, your settlement account, your VBA, or kept in the customer VBA) |
| Fee bearer | Who pays deposit processing fees — the customer (default) or you as sponsor |
Last updated on