Virtual accounts service
Issue a Naira virtual account
/virtual-accountsvirtual_accounts:writeAuth Bearer keyIdempotentIssues a NGN virtual account. For an existing, KYC-verified customer this creates a dedicated account for that customer; for the business it creates (or returns) its own deposit account. Account name precedence: the request's `account_name`, then the customer's KYC-verified legal name, then a generic `BUSINESS <id>` placeholder. A blank or whitespace-only `account_name` counts as omitted, so the next rule applies. The named request and response examples below show each outcome: an override, the verified-name default, and the placeholder fallback. Caveat: dedicated accounts are registered through our payment partner (Nomba), and the payer's bank controls how the account name is displayed when sending — the exact string a sender sees is not guaranteed.
Headers
Idempotency-KeystringrequiredRetrying with the same key and payload replays the original response.
Request body
{
"customer_id": "cus_3a0912b25bc208cfa1069cbb",
"currency": "NGN",
"account_name": "Justxpend Wallet - Chidi Okeke",
"reference": "VA-CHIDI-0001"
}Responses
201Virtual account issued. The `account_name` on the response shows which rule won for that request — compare it with the matching request example.
{
"id": "va_9f2b1c7a4d8e6f0a3b5c7d91",
"object": "virtual_account",
"status": "active",
"currency": "NGN",
"account_name": "Justxpend Wallet - Chidi Okeke",
"account_number": "9902117364",
"bank_name": "Nombank MFB",
"account_type": "dedicated",
"customer_id": "cus_3a0912b25bc208cfa1069cbb",
"reference": "VA-CHIDI-0001",
"metadata": {},
"created_at": "2026-10-07T05:12:44.000Z"
}Errors
Errors use RFC 9457 problem details. Branch on code, and log request_id.
400Bad request401Unauthenticated403Forbidden409Idempotency conflict422Validation error. `errors` lists each invalid field. Fix the request and resend with a new Idempotency-Key.429Rate limited503Account issuance could not be confirmed. An account may already exist. Retry only with the same Idempotency-Key and reference; never create a new request to bypass a hold. pending_confirmation or needs_review may require support reconciliation.curl -X POST "https://business.boundlesspay.com/api/public/v1/virtual-accounts" \
-H "Authorization: Bearer $BOUNDLESS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "customer_id": "cus_3a0912b25bc208cfa1069cbb", "currency": "NGN", "account_name": "Justxpend Wallet - Chidi Okeke", "reference": "VA-CHIDI-0001" }'