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 (cus_… or legacy public id).

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 (v0.11-8): 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.

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})$
object
enum<string>

Resource type discriminator. Always "virtualAccount".

Available options:
virtualAccount
customerId
string

The OMS customer that owns this record (cst_ 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})$
customer
object

Display-safe summary of the owning customer (customer.id equals customerId). Returned on list and detail responses.

status
enum<string>

Current lifecycle status of the virtual account.

Available options:
pending,
active,
frozen,
closed,
deleted,
failed,
inactiveActionRequired
sourceToDestination
enum<string>

Corridor composite derived from the destination type — fiatAccountToCrypto for a crypto-wallet destination (inbound fiat auto-converts), or fiatAccountToFiatAccount for a bank or walletFiat destination (inbound USD forwarded onward — the same token for both; walletFiat introduces no new corridor).

Available options:
cryptoToCrypto,
cryptoToCash,
cryptoToFiatAccount,
cashToCrypto,
fiatAccountToCrypto,
fiatAccountToFiatAccount
statusReason
string

Human-readable explanation of the current status.

source
object

Expected inbound rail detail.

depositInstructions
object

Bank coordinates senders use to deposit into this Virtual Account. Null until the provider has opened the account, so a pending Virtual Account carries none.

provider
string

The institution that issues and custodies this Virtual Account — currently "Erebor Bank, N.A." or "Coinme Inc.". 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 entity an outbound forward is sent under — that is payoutOrigin.accountHolderName, which is set by whoever executes the payout 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 the vendor is unrecognized.

payoutOrigin
object

Where the onward forward of an inbound deposit is sent from, and whose legal identity it goes out under. Response-only, derived from the destination type and the issuing institution. A bank destination renders the bank arm; a crypto-wallet destination renders the blockchain arm with a null accountHolder, since a crypto payout has no sending legal identity. Absent for a walletFiat destination, whose delivery is an internal ledger movement rather than a payout. accountHolder and accountHolderName are also null whenever OMS cannot name the issuing institution.

destination
OMS wallet · object

V0.10: unified side shape.

returnDestination
US bank account · object

The configured fiat return destination (v0.11-8) for failed outbound legs; absent/null when none is set (the project return policy applies instead, once T13 wires the waterfall).

sponsorGas
boolean

Whether OMS absorbs the on-chain gas cost for the destination delivery. Persisted from the create/update request (currently only true is accepted).

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.

failureReason
enum<string>

Set when status = failed; closed enum identifying the failure category.

Available options:
provisioningTimeout,
systemError,
ereborRejected,
deletePendingTimeout,
coinmeDeclined
deletionRequestedAt
string<date-time>

Set when DELETE has been requested but the close webhook has not yet finalized.

deletionRequestedBy
string

Identity (JWT subject claim) of the caller who invoked DELETE.

finalBalance
object

DDA balance snapshot at the moment the VA flipped to deleted.