Skip to main content
POST
Create a virtual bank account
Requires scope: manage:accounts — see Required scopes. Provisions a virtual bank account. Provide a display name, the fiat inCurrency to receive (EUR provisions a EUR_SEPA IBAN, USD a USD_ACH account), the targetCryptocurrency incoming funds convert to, and a unique idempotencyKey (safe retries). The response includes the bank coordinates — IBAN/BIC for EUR, account and routing number for USD — and a referenceCode the payer must quote so the wire is matched to this account.
The account must be verified (and have a linked account-holder party) before a virtual bank account can be created. See Account verification.

Errors

The codes this endpoint can return, in addition to the standard errors. Branch on code, never the message.

Authorizations

Headers

x-tenant-id
string<uuid>

Which tenant the request is scoped to, among those your token grants. Omit it when the token grants exactly one tenant; it is required when the token grants more than one. A supplied value must exactly match a tenant the token grants.

Absent when required, blank, malformed, or naming a tenant the token does not grant — each gets the same generic 403 forbidden, which reveals neither whether a tenant exists nor which ones you may use. Send the header once: a repeated header is rejected the same way.

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Path Parameters

accountId
string<uuid>
required

Unique account identifier

Body

application/json

Request to create a virtual bank account. The rail is resolved from inCurrency and your tenant's enabled pay-in configuration (EUR → SEPA, USD → ACH).

name
string
required

Display name for the bank account

Maximum string length: 255
inCurrency
string
required

Fiat currency to receive (ISO 4217). Determines the bank account type (EUR -> EUR_SEPA, USD -> USD_ACH)

Pattern: ^[A-Z]{3}$
targetCryptocurrency
string
required

Cryptocurrency to convert incoming fiat payments to (e.g. USDC)

Pattern: ^[A-Za-z0-9]{2,10}$
idempotencyKey
string
required

Unique key to prevent duplicate operations on retry

Maximum string length: 255
ownershipProof
object

Customer-signed wallet-ownership proof. Required where the virtual bank account settles to a self-custody account wallet that must prove control first — the destination is the customer's own wallet, so Venly cannot sign the proof itself.

Obtain message from prepare, have the customer sign it verbatim with the destination wallet, and submit it here. Ignored where no proof is required, so it is safe to send unconditionally.

Response

Virtual bank account created

success
boolean

Indicates whether the request was successful

result
object

Virtual bank account for receiving fiat payments that are auto-converted to crypto. EUR_SEPA accounts return iban/bic; USD_ACH accounts return accountNumber/routingNumber. Read depositRails for the complete instruction set per rail — the summary fields below always describe the primary rail.