Skip to main content
POST
Create a Virtual Account

Authorizations

Authorization
string
header
required

Token from POST /auth/token

Headers

Idempotency-Key
string
required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Body

application/json

Create a Virtual Account: the inbound bank rail plus the destination that receives the converted funds.

customerId
string
required

Owning customer ID (cst_ prefix).

source
object
required

Expected inbound bank rail.

destination
US bank account · object
required

Where to deliver the deposited value — a crypto wallet (auto-convert), a bank account (forward onward), or a walletFiat fiat wallet (hold as a USD balance). An external crypto wallet must be a registered External Account; raw addresses are not accepted here. walletCrypto is available only where the institution issuing the Virtual Account custodies wallets itself, and is otherwise rejected with 422 DestinationWalletCryptoNotSupported. asset and network are validated against the resolved External Account or wallet.

type
string
required

Closed for Alpha: must be "bankUs".

returnDestination
US bank account · object

Optional fiat return destination: where inbound fiat is sent if the outbound leg can't be completed. Bank arms only in v1 — bankUs / bankIban / bankCanada (network swift, USD); walletFiat and bankCanada with network local (CAD) are rejected with 422 RailNotSupported.

sponsorGas
boolean
default:true

When true, OMS absorbs the on-chain gas cost for the destination delivery. Only true is currently supported.

bankMemo
string

Optional wire/ACH memo the customer can include.

label
string

Partner display label.

metadata
object

Free-form key-value pairs stored on the resource and echoed back on reads.

Response

The request has succeeded and a new resource has been created as a result.

A dedicated bank account number issued for a customer. Inbound fiat deposits are automatically converted and delivered to the configured destination, creating a transaction per deposit.

customer
object
required

The customer that owns this record.

id
string

Virtual Account ID (va_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
status
enum<string>

Current lifecycle status of the virtual account.

Available options:
pending,
active,
frozen,
closed,
deleted,
failed,
inactiveActionRequired,
deleting
failure
object

Why the virtual account failed. Present only when status is failed.

hold
object

What you must do for a virtual account in inactiveActionRequired: set a new destination. Present only in that status.

depositInstructions
object

Bank coordinates senders use to deposit into this Virtual Account. Left out until the provider has opened the account, so a pending Virtual Account carries none. Still present while it is deleting, and left out again once the account has ended, since a closed, failed or deleted Virtual Account can no longer receive a deposit. Capture it while the account is live if you need it for your own records.

provider
string

The institution that issues and custodies this Virtual Account — currently "Erebor Bank, N.A." or "Cross River Bank". Assigned by OMS from your project's configuration, never supplied by you. Read it when you need to tell an end user or a support ticket which institution is holding the deposited funds. It is not the name a payout is sent under, which is the payout transfer's originatorName and can name a different company. New providers may be added, so treat the string as free-form rather than a fixed set. Read-only; omitted when OMS cannot determine the institution.

destination
OMS wallet · object

The account deposits are paid out to. A bank account carries no rail and no ACH options; they are on payout.

payout
object

How a deposit is paid out to a bank or walletFiat destination: the rail and, on ach and achSameDay, the ACH options. Left out for a crypto destination.

payoutOrigin
object

Whose name a payout from this Virtual Account goes out under. Left out for a walletFiat destination or none.

returnDestination
US bank account · object

Where inbound fiat is sent back when its payout cannot be completed. It carries no rail; a bank return destination's rail is on returnPayout. Present only when you set one.

returnPayout
object

How a deposit is returned to a bank returnDestination: only the rail. Left out with no return destination.

sponsorGas
boolean

Whether OMS absorbs the on-chain gas cost for the destination delivery. Present only when true, the only value a create or update request accepts.

bankMemo
string

Wire/ACH memo the customer can include with deposits.

label
string

Partner display label.

metadata
object

Free-form key-value pairs supplied at creation or update.

createdAt
string<date-time>

When the virtual account was created.

updatedAt
string<date-time>

When the virtual account was last updated.

deletionRequestedAt
string<date-time>

When a delete was accepted. Present only after a delete.