Create a static virtual account for a customer
Opens a permanent Providus Bank account number named
<business short name> / <customer name>. Every transfer into it is matched to that customer and settles
into settlement_account_id (default: the Naira · Main account), or, with own_account: true, into a new
sub-account opened for this customer. The customer is saved (see listCollectionCustomers). Partner call:
503 on failure, nothing is created (nor the sub-account); retry with the same Idempotency-Key.
Error codes: invalid_api_key, parameter_invalid, parameter_missing, resource_not_found, scope_missing, csrf_token_invalid, idempotency_key_reused, bank_unavailable, account_closed, currency_mismatch, rate_limited.
Authorizations
Server API key, scoped. pk_test_ keys hit the sandbox tenant.
Headers
Optional on non-money POSTs; honoured when sent.
1 - 255Optional client correlation id, up to 128 characters. It is not echoed: the response's X-Request-Id is always
our own req_… id. We log your value with the request as client_request_id, so support can find a request by
either id. A longer value is refused with 400 parameter_invalid.
128Body
settlement_account_id and own_account: true can't be sent together (400 parameter_invalid, param: own_account).
Shown to the sender as <business short name> / <customer name>.
1 - 80A saved customer (cus_…). When sent, customer_name and customer_email default to theirs.
254Your own id for the customer (e.g. CUST-0042). Returned on every inbound credit and webhook.
64Account the money lands in (acc_…). Defaults to the business's Naira · Main account. Any of the
business's active accounts in the same currency: Main, Payroll or a sub-account. Agent accounts are not
allowed (an agent's money comes only from top-ups the team makes, within its limits). Payments are
credited to this account directly.
404 resource_not_found if it isn't one of the business's accounts; 403 account_closed if it is closed; 422
currency_mismatch if it is in another currency; 400 parameter_invalid with param: settlement_account_id for an
agent account, or one still opening.
Give this customer's payments a balance of their own. PanoFlow opens a new sub-account named after the
customer (type: sub, e.g. "Kano Freight Services", shown as "Naira · Kano Freight Services"; cut to 40
characters, with " 2", " 3" … added if the name is taken) and the number settles into it. It is returned
as settlement_account.
It is an ordinary sub-account, the same as one opened with createAccount: its own balances, statements
and transactions, an account.opened webhook, and it can be renamed, moved out of or closed like any
other. Closing the virtual account leaves the sub-account and its money as they are. Opening it follows
createAccount's rules (owner or admin; role_not_permitted otherwise).
Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.
Response
The new virtual account.
A static virtual account (sva_…), a permanent account number for one customer.
sva_…
Always virtual_account.
"virtual_account"RFC 3339, UTC.
"2026-10-27T08:41:00Z"
RFC 3339, UTC.
"2026-10-27T08:41:00Z"
Always static. Per-invoice accounts are on the invoice.
"static"The customer (payer) on an invoice or static virtual account.
Name the sender's bank shows.
10-digit Nigerian NUBAN account number.
^\d{10}$"8012457739"
Partner bank.
ISO 4217. Only NGN is live at launch; others return 422 currency_not_enabled.
NGN, USD, GBP, EUR, GHS, KES One of the business's own PanoFlow accounts (owned by the Accounts service).
active accepts transfers; closed does not (the bank rejects them). Closed accounts can be reopened.
active, closed Credits received.
Total received.
Your own id for the customer.
The bank's NIBSS NIP institution code (CBN bank code).
"058"
RFC 3339, UTC.
"2026-10-27T08:41:00Z"
RFC 3339, UTC.
"2026-10-27T08:41:00Z"
Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.