Skip to main content
POST
Issue Bank Account
Issues an NGN or USD deposit account for an approved account. The banking provider is selected automatically based on the currency and whether the account is a business or an individual. The details each provider needs are prefilled from the account’s application. Check Get Issuance Requirements first to see the prefilled payload and anything missing, then pass the missing pieces in accountData.

​
NGN accounts

NGN accounts are issued immediately.

​
USD accounts

Every USD account we open is a real bank account — the first one and every one after it. Each has its own account number, in the client’s name, at the same bank. There is no “physical” tier and no “virtual” tier: accounts opened later are not virtual accounts layered over the first.You will see the term anyway, because our storage for deposit accounts is called virtual accounts — which is why the webhook announcing even a client’s first USD account is account.virtual_account.created. That is an internal name, not a product distinction.The only real distinction is primary vs additional, and it is visible on every account as the reference field: null on the primary, set on the ones you named. See Multiple USD deposit accounts below.
USD accounts require review. The first call records the request and returns 202 Accepted; the deposit account is set up once the request is approved:
requestId identifies this request — quote it when asking us about a request that is taking longer than you expect. Call the endpoint again once the account is approved — the response then includes the deposit account with accountNumber, routingNumber and swiftCode. While review is in progress, repeat calls keep returning 202 with the same requestId, so retrying is safe and never creates a second request.
Rather than polling, subscribe to account.virtual_account.created — it fires as soon as the deposit account exists, with the account details in the payload.

​
Individual USD accounts

Individual accounts have no representatives. When the account was onboarded with its identity details via Update Individual Details (idDocument, address.line2, and a tax number from taxId / nin / bvn) — plus the passport/ID from the completed Sumsub KYC — no extra payload is needed:
You only need accountData.onboardingDetails to override a field that wasn’t set on the account, e.g.:

​
Multiple USD deposit accounts

A client can hold more than one USD deposit account, each with its own account number. Pass a reference — your own stable id for whatever you need to reconcile separately, such as a storefront, a branch, a marketplace or a channel:
Only the account number differs — bank name, routing number and account holder are shared, because all of these accounts belong to one client at the same bank. Each is still a real account with its own number, not a label over the primary. That account number is what separates the money: funds sent to it are credited against that reference, so you can tell which source a deposit came from without reconciling by amount or sender name. reference and label are echoed back on List Bank Accounts and Get Funding Instructions, so you can hand the right details to the right source without keeping your own mapping. The client’s primary account is the one issued without a reference, and it reports reference: null. That field is the reliable way to tell the two apart, and it is returned on List Bank Accounts and Get Funding Instructions as well as at creation — so you can classify an account at any time rather than having to remember the order you created things in. A client can only ever hold one account with reference: null: a second call without a reference returns the existing account rather than opening another.
The reference is the idempotency key. The same reference always returns the same account with status: already_exists, so a retry, a duplicated job or a replayed request can never mint a second account for one source. There is no cap on how many references a client can have.
Requesting an additional account requires the client to already hold its primary account — that is what proves the provider approved the entity. Issue one without a reference first, or the call is rejected.Additional accounts are USD only. A reference with currency: "NGN" returns 400; for per-customer NGN accounts use the customer virtual account endpoint instead. Not every USD provider can issue more than one account per client — where it can’t, the call returns 400 explaining so.

​
Key Behaviours

Entries in accountData.representatives are merged into the prefilled representative with the same relatedPersonId, so you only send the fields you’re adding — names, addresses and ownership come from the application. Individual accounts use accountData.onboardingDetails instead (see above).
The account’s application must be approved before bank accounts can be issued. If provider-required details are missing, the response lists them under errors (USD) or missingFields (NGN).
Re-issuing. A USD call without a reference returns the client’s existing account with status: already_exists (200) rather than creating another — safe to retry. A USD call with a reference behaves the same way per reference. NGN is one account per provider and returns 409 Conflict once one exists.

Authorizations

​
X-API-Key
string
header
required

Your Rolla API key

Path Parameters

​
accountId
string<uuid>
required

Identifier of an account owned by the same user as your API key's business

Body

application/json
​
currency
enum<string>
required
Available options:
NGN,
USD
​
accountData
object

Optional overrides merged over the details prefilled from the account's application. The shape depends on the provider — call GET /accounts/{accountId}/bank-accounts/requirements to see the prefilled payload and what's missing. For USD, entries in representatives merge into the prefilled person matching the same relatedPersonId.

​
reference
string

Your own stable id for whatever you need to reconcile separately — a storefront, a branch, a marketplace, a channel. Supplying it issues an additional deposit account under the same client, with its own account number, so incoming funds are attributable to that one reference. Omit it for the client's primary account.

Idempotent: the same reference always returns the same account, so a retry cannot create a duplicate. USD only, and only on providers that support more than one account per client.

Required string length: 1 - 100
Example:

"store-amazon-uk"

​
label
string

Human-readable name stored alongside the account and echoed back on reads, e.g. "Amazon UK".

Required string length: 1 - 120
Example:

"Amazon UK"

Response

Bank account issued

​
success
boolean
Example:

true

​
message
string
Example:

"Bank account issued successfully"

​
data
object