account.funded for it. What you do need to do is give each customer their new account number before the cut-over date.
What happens, in order
- A replacement is opened. If your customer already has a Nombank account with you, that account becomes the replacement. Otherwise we open one using the BVN or NIN you gave us. You don’t receive
account.issuedfor a replacement. - You are told. You receive one
account.replacedwebhook per account, with the old and new numbers and the cut-over date. Your business’s Owners and Admins also get an email with the count and the date. - Before the cut-over date, the old account is still your customer’s default account, and lists show it first. The replacement appears beside it with
replacesset. - From the cut-over date, the old account is no longer listed; its replacement is the customer’s default.
GET /v1/virtual-accounts/replacementsandaccount.replacedstill name both. The old number keeps receiving payments, credited to your customer as before.
Fields on a customer account
GET /v1/virtual-accounts?customer_id=… and GET /v1/customers/{id}/virtual-accounts return these fields alongside the usual ones:
The full list
GET /v1/virtual-accounts/replacements returns every replaced account for your business: the old and new account details, replaced_at, cutover_at and retired. Add ?format=csv to download it as a spreadsheet with these columns:
customer_id, customer_reference, previous_virtual_account_id, previous_account_number, previous_bank_name, previous_bank_code, new_virtual_account_id, new_account_number, new_account_name, new_bank_name, new_bank_code, replaced_at, cutover_at
Customers Nombank can’t serve
- Nombank already holds two accounts for the customer’s BVN or NIN: they are moved to Paga instead. A customer whose old account is at Paga keeps it; a PalmPay customer is given their live Paga account, or a new one, and you’re told through
account.replacedlike any other replacement. - No BVN or NIN on file, or Nombank refused for another reason: the customer keeps their old account, listed and receiving payments. Nothing is hidden for them. To collect from them now, use a dynamic account with the customer’s BVN as
id_number.

