Virtual bank accounts

A virtual bank account (VBA) gives an account its own bank coordinates to receive fiat. Incoming credits are automatically converted to a stablecoin and credited to the account’s wallet.

Prerequisites

The account must be verified and have a linked account-holder party.

Lanes

The rail is resolved from the inCurrency you request and your tenant’s enabled pay-in configuration — you don’t pick a provider.

Lane	`bankAccountType`	Returns	Notes
EUR → SEPA	`EUR_SEPA`	`iban` + `bic`	Deposit rails may populate asynchronously shortly after creation, so the account can come back `PENDING` first.
USD → ACH	`USD_ACH`	`accountNumber` + `routingNumber`	Returned synchronously. Requires your tenant to be onboarded for the USD lane with an approved KYB recording. Typically also reachable over WIRE, RTP and SWIFT.

Create a virtual bank account

Provide a display name, the fiat inCurrency, the targetCryptocurrency to convert to, and a unique idempotencyKey:

curl -X POST https://api.venlyfinance.com/v1/accounts/{accountId}/virtual-bank-accounts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EUR Deposits",
    "inCurrency": "EUR",
    "targetCryptocurrency": "USDC",
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

Response

{
  "success": true,
  "result": {
    "id": "4d5e6f70-8192-4a3b-9c4d-5e6f7081920a",
    "bankAccountType": "EUR_SEPA",
    "status": "ACTIVE",
    "currency": "EUR",
    "targetCryptocurrency": "USDC",
    "iban": "DE89370400440532013000",
    "bic": "DEUTDEDB",
    "bankName": "Example Bank",
    "beneficiaryName": "Jane Doe",
    "referenceCode": "VFY-7K2Q-931",
    "depositRails": [
      {
        "railType": "SEPA",
        "iban": "DE89370400440532013000",
        "bic": "DEUTDEDB",
        "bankName": "Example Bank",
        "beneficiaryName": "Jane Doe",
        "paymentReference": "VFY-7K2Q-931"
      }
    ]
  }
}

The fields that matter

Field	Why it matters
`depositRails`	The complete instruction set per rail. Read this to render payment instructions — it carries the bank and beneficiary postal addresses that wire and SWIFT senders require, which the summary fields don’t.
`iban` / `bic`	Account coordinates for EUR rails.
`accountNumber` / `routingNumber`	Account coordinates for US rails.
`beneficiaryName`	The legal name on the account — display it next to the coordinates.
`referenceCode`	Critical. The payer must quote this in the payment reference so the incoming credit is matched to this account. Without it, settlement falls back to manual reconciliation.
`targetCryptocurrency`	The stablecoin incoming fiat is converted to.
`status`	`PENDING`, `ACTIVE` or `CLOSED`.

Always surface the referenceCode to the end user and tell them to include it in their transfer. It’s how an incoming credit is routed to the right account.

Summary fields vs. `depositRails`

The top-level iban/bic/accountNumber/routingNumber fields always describe the primary rail. depositRails lists every rail the account is reachable over. A USD account typically exposes four rails sharing the same account and routing number — except SWIFT, which carries a BIC instead of a routing number:

`railType`	Coordinates
`ACH`	`accountNumber` + `routingNumber`
`WIRE`	`accountNumber` + `routingNumber`, plus bank and beneficiary addresses
`RTP`	`accountNumber` + `routingNumber`
`SWIFT`	`accountNumber` + `bic`

A EUR account exposes a single SEPA rail.

Build your payment-instruction UI from depositRails rather than the summary fields. If you only render iban/accountNumber, a customer sending by wire or SWIFT will be missing the bank address their bank asks for.

`PENDING` accounts

On the EUR lane, an account can come back status: PENDING with bankAccountType omitted — the provider hasn’t returned the deposit rails yet. Don’t show payment instructions until it reaches ACTIVE and depositRails is populated. Register a webhook to hear about the transition instead of polling.

Proving wallet ownership

On some setups, converted funds settle straight to the customer’s own self-custody wallet. Where that applies, the customer must prove they control that wallet first — Venly can’t sign for a wallet it doesn’t hold the keys for. You don’t need to know up front whether this applies to you. Call prepare: if a proof is required you get the exact message to sign, and if it isn’t you get 400 ownership-proof-not-applicable and can create the account directly.

Ask for the message

POST /accounts/{accountId}/virtual-bank-accounts/prepare with the destination walletAddress and blockchain.Nothing is persisted — no preparation id, no expiry. Two calls for the same account and wallet return an equivalent message, so this is safe to repeat.

Have the customer sign it verbatim

The customer signs message exactly as returned, blind. It embeds an opaque provider token, so don’t reformat, re-encode, pretty-print, or reconstruct it — the signature is checked against those exact bytes.

Submit it with the create call

Include the ownershipProof block — walletAddress, blockchain, message, signature — when creating the virtual bank account.

Where a proof isn’t required the ownershipProof field is ignored, so you can send it unconditionally if that is simpler than branching. Only an externally-owned account can sign: the scheme is EIP-191, and ERC-1271 contract signatures are not supported. A smart-contract wallet cannot complete this step.

Code	Meaning
`ownership-proof-required`	This account requires a signed proof, but no `ownershipProof` block was supplied.
`ownership-proof-not-applicable`	This account doesn’t need a signed proof — create it without one.
`invalid-proof-message`	The message is malformed, or doesn’t reference the wallet address and embedded token.
`signature-mismatch`	The signature doesn’t recover the supplied wallet address. The provider is never called.

Verification gates

Provisioning onboards the account holder for verification, so their verification state can block you.

A verified party is not automatically ready. The account holder must also have accepted our partners’ terms themselves — see Partner-terms consent. Until that acceptance is recorded, provisioning is blocked, and the fix is to present the party’s consent link to your end customer rather than to retry.

These states can block you:

Status	Code	What to do
`409`	`recipient-verification-pending`	The account holder’s verification is still pending. Retryable — retry once approved.
`422`	`recipient-verification-rejected`	Verification was rejected or revoked. Provisioning cannot proceed.
`503`	`identity-verification-unavailable`	Transient. Retry with backoff.

Reading them back

List virtual bank accounts for an account.
Get a virtual bank account by ID.

Next steps

Wallets & balances

Where converted funds land.

Pay-outs

The other direction: crypto out, fiat to a bank beneficiary.

Supported chains & assets

Which fiat currencies and stablecoins are supported.

Webhooks

Hear about deposits and rail population without polling.

Overview

Recipes

Onboarding & Verification

Core Concepts

Parties

Accounts

Supported Assets

Wallets

Transfers

Fiat to Crypto Payment Sessions

Payout Bank Accounts

Payout Routes

Payouts

Permits

Allowances

Webhooks

Reference

Virtual bank accounts

Prerequisites

Lanes

Create a virtual bank account

The fields that matter

Summary fields vs. `depositRails`

`PENDING` accounts

Proving wallet ownership

Verification gates

Reading them back

Next steps

Wallets & balances

Pay-outs

Supported chains & assets

Webhooks

​Prerequisites

​Lanes

​Create a virtual bank account

​The fields that matter

​Summary fields vs. depositRails

​PENDING accounts

​Proving wallet ownership

​Verification gates

​Reading them back

​Next steps

Wallets & balances

Pay-outs

Supported chains & assets

Webhooks

Prerequisites

Lanes

Create a virtual bank account

The fields that matter

Summary fields vs. `depositRails`

`PENDING` accounts

Proving wallet ownership

Verification gates

Reading them back

Next steps