Create a Virtual Account
Create a Virtual Account for a customer. Partner must have virtual_account_provider configured.
Authorizations
Token from POST /auth/token
Headers
Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.
Body
Create a Virtual Account: the inbound bank rail plus the destination that receives the converted funds.
Owning customer (cus_… or legacy public id).
Expected inbound bank rail.
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.
- US bank account
- IBAN bank account
- Canadian bank account
- OMS wallet
- External wallet (registered)
- Fiat wallet
Closed for Alpha: must be "bankUs".
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.
- US bank account
- IBAN bank account
- Canadian bank account
- Fiat wallet
When true, OMS absorbs the on-chain gas cost for the destination delivery. Only true is currently supported.
Optional wire/ACH memo the customer can include.
Partner display label.
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.
Virtual Account ID (va_ prefix).
^[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})$Resource type discriminator. Always "virtualAccount".
virtualAccount The OMS customer that owns this record (cst_ prefix).
^[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})$Display-safe summary of the owning customer (customer.id equals customerId). Returned on list and detail responses.
Current lifecycle status of the virtual account.
pending, active, frozen, closed, deleted, failed, inactiveActionRequired 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).
cryptoToCrypto, cryptoToCash, cryptoToFiatAccount, cashToCrypto, fiatAccountToCrypto, fiatAccountToFiatAccount Human-readable explanation of the current status.
Expected inbound rail detail.
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.
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.
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.
V0.10: unified side shape.
- OMS wallet
- External wallet
- Fiat wallet
- US bank account
- IBAN bank account
- Canadian bank account
- Card
- Cash
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).
- US bank account
- IBAN bank account
- Canadian bank account
- Fiat wallet
Whether OMS absorbs the on-chain gas cost for the destination delivery. Persisted from the create/update request (currently only true is accepted).
Wire/ACH memo the customer can include with deposits.
Partner display label.
Free-form key-value pairs supplied at creation or update.
When the virtual account was created.
When the virtual account was last updated.
Set when status = failed; closed enum identifying the failure category.
provisioningTimeout, systemError, ereborRejected, deletePendingTimeout, coinmeDeclined Set when DELETE has been requested but the close webhook has not yet finalized.
Identity (JWT subject claim) of the caller who invoked DELETE.
DDA balance snapshot at the moment the VA flipped to deleted.