Skip to main content
POST

Overview

Generate a single-use NGN account for a customer, for an amount and a lifespan (5 to 1440 minutes). Show the payer the account, the amount and expires_at. customer_id can be our customer id or your own; with the customer’s details in the request, a new customer is created under your id (see Use your own customer ids; on this route customer_date_of_birth is always required for a new customer).

The bank

Dynamic accounts open at Nombank MFB. Show the payer the bank_name from the response. A Nombank dynamic account takes exactly amount and stops accepting payments at expires_at: the payer’s bank refuses any other amount and any late transfer.
  • Nombank opens an account only against the customer’s BVN or NIN. Send the BVN as id_number (11 digits) when none is on file; it is used for this account. A BVN other than the one verified for the customer answers 409 customer_id_conflict. With no BVN or NIN at all: 422 identity_required, data.field id_number.
  • Nombank holds at most two accounts per BVN or NIN. Leave bank out and a customer at that limit gets a Paga account in the same request (bank_name Paga; a Paga account adds its collection fee to what the payer sends). With "bank": "nombank" the answer is 422 nomba_identity_limit.
  • Nombank can’t be reached, or didn’t confirm the account: 503 issuing_unavailable, retryable. No account is given to you; retry with the same reference, and contact support if it persists.
  • bank other than nombank or paga: 400 invalid_bank.
Without reference, a customer has one open account at a time, whichever bank opened it; a repeat for the same amount returns it, and a different amount gets a new account.

Order reference

Send your order id as reference (or order_reference) to give the order its own account. The response returns it as order_reference, and account.funded carries it as reference, with expected_amount. Repeating the request with the same reference, customer and amount while the account is open returns the same account. Any other reuse answers 400 duplicate_reference (data.status expired once the account has expired). Without reference, a customer has one open account per bank at a time: a repeat for the same amount returns it, and a different amount gets a new account (the earlier one still credits whatever is paid into it). A payment of a different amount, or after expires_at, is still credited; a late one is marked "late": true on the webhook. See Collecting payments per order.

Authorizations

X-API-Key
string
header
required

API key for authentication.

Body

application/json

Name the customer with customer_id or customer_reference (exactly one is required). The customer_* fields are read only when the customer does not exist yet.

amount
number
required

The amount to collect (NGN). Payments of another amount are still credited; compare expected_amount and paid_amount on account.funded.

lifespan_minutes
integer
required

How long the account stays open, in minutes (5 to 1440).

Required range: 5 <= x <= 1440
customer_id
string

Required unless you send customer_reference. Our customer id, or your own id for the customer. We look it up within your business: our id first, then a customer whose reference is this value. If neither matches and the request carries the customer's details (customer_* fields), the customer is created with this value as their reference (1 to 64 characters: letters, digits, and _ . : -). Without details, an unknown id answers 400 customer was not found.

Example:

"CUST-10293"

reference
string

Your own reference for the order this account collects. 1 to 64 characters: letters, digits, and _ . : -. Unique among your business's one-time accounts. Returned as order_reference and sent as reference on account.funded.

Example:

"ORDER-7781"

order_reference
string

Same as reference. Send one of them.

customer_reference
string

Required unless you send customer_id. Your own id for the customer, by its explicit name. Works the same way as your id in customer_id, including creating a new customer from the customer_* fields. Send this or customer_id, not both.

Example:

"CUST-10293"

customer_name
string

New customer: full name, split at the first space into first and last name. Required unless you send customer_first_name and customer_last_name.

Example:

"Ada Obi"

customer_first_name
string

New customer: first name. Send with customer_last_name, or send customer_name instead.

customer_last_name
string

New customer: last name. Send with customer_first_name, or send customer_name instead.

customer_email
string<email>

New customer: required. A valid email address, unique among your customers.

customer_phone
string

New customer only. Required.

Example:

"08030000000"

customer_country_code
string

New customer: two-letter ISO country code. Defaults to NG.

customer_date_of_birth
string<date>

New customer: required. YYYY-MM-DD.

customer_gender
enum<string>

New customer: optional. male or female.

Available options:
male,
female
bank
enum<string>

Leave out (recommended): Nombank MFB, or Paga when Nombank already holds two accounts for the customer's BVN or NIN. nombank allows Nombank only. A Nombank account accepts exactly amount and stops at expires_at.

Available options:
nombank,
paga
Example:

"nombank"

id_number
string

The customer's BVN, used for this account when none is on file (Nombank opens accounts only against a BVN or NIN). Must match the BVN verified for the customer, if any.

Pattern: ^[0-9]{11}$
Example:

"22212345678"

Response

Dynamic virtual account created successfully

status
boolean
data
object
error
any[]
message
string