Create Dynamic Virtual Account

Mint a one-time collection account for a specific amount. Unlike a customer or business virtual account (which is reusable), a dynamic account is intended for a single payment — typically a checkout or a pay-by-transfer flow where each order gets its own account number. When it’s funded, the money credits your wallet and a FUNDING_NOTIFICATION webhook fires.

When to use it

Account type	Reusable	Best for
Customer / Business VA	Yes	A payer who pays you repeatedly
Dynamic	No (one-time)	A single checkout / order, amount known upfront

Endpoint

POST /api/v1/business/virtualaccount/dynamic

Signature required: Yes

Headers

Header	Required	Description
`X-Numero-Api-Key`	Yes	Your API key
`X-Numero-Signature`	Yes	Base64 HMAC-SHA256 over the exact raw request body (POST) or the canonicalised query string (GET), keyed with your Public Key. See Request signing.
`X-Numero-Signature-Version`	Yes	Always `v2`.

Request body

Field	Type	Required	Description
`amount`	number	Yes	Exact amount to collect, in major units (naira)
`firstName`	string	No	Payer’s first name
`lastName`	string	No	Payer’s last name
`email`	string	No	Payer’s email
`mobileNumber`	string	No	Payer’s phone number
`bvn`	string	No	Payer’s BVN (where the provider requires it)
`reference`	string	No	Your own reference for the collection
`expiresInMinutes`	integer	No	Minutes until the account lapses
`narration`	string	No	Narration to attach to the collection

Request example

curl -X POST "https://api.usenumero.com/numeroaccount/api/v1/business/virtualaccount/dynamic" \
  -H "Content-Type: application/json" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: $SIGNATURE" \
  -H "X-Numero-Signature-Version: v2" \
  -d '{
    "amount": 5000,
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "mobileNumber": "08012345678",
    "reference": "order_10231",
    "expiresInMinutes": 30,
    "narration": "Order #10231"
  }'

Response

{
  "data": {
    "reference": "DVA-20240115-abc123",
    "accountName": "John Doe",
    "accountNumber": "8012345678",
    "bankName": "Providus Bank",
    "amount": 5000,
    "expiresAt": "2024-01-15T12:30:00Z"
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}

Field	Type	Description
`reference`	string	Unique reference for this collection
`accountName`	string	Name on the virtual account
`accountNumber`	string	NUBAN to share with the payer
`bankName`	string	Bank the account was created with
`amount`	number	Amount the account expects
`expiresAt`	datetime	When the account lapses (if `expiresInMinutes` was set)

When the payer transfers into this account, funds are credited to your wallet (held and released per your settlement schedule) and a FUNDING_NOTIFICATION webhook is delivered to your subscription URL.

Getting Started

Transfers & Payouts

Collections (Virtual Accounts)

Wallet-as-a-Service

Customers

Invoices

Cards

Cardholders

Balance & Transactions

Value Added Services

Credit

Verification / KYC

Webhooks

Create Dynamic Virtual Account

When to use it

Endpoint

Headers

Request body

Request example

Response

​When to use it

​Endpoint

​Headers

​Request body

​Request example

​Response

When to use it

Endpoint

Headers

Request body

Request example

Response