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), the targetCryptocurrency incoming funds convert to, and a unique idempotencyKey (safe retries). The response includes the IBAN/BIC 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

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)

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.