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 ID (cst_ prefix).
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: 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.
The customer that owns this record.
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})$Current lifecycle status of the virtual account.
pending, active, frozen, closed, deleted, failed, inactiveActionRequired, deleting Why the virtual account failed. Present only when status is failed.
What you must do for a virtual account in inactiveActionRequired: set a new destination. Present only in that status.
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.
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.
The account deposits are paid out to. A bank account carries no rail and no ACH options; they are on payout.
- OMS wallet
- External wallet
- Fiat wallet
- US bank account
- IBAN bank account
- Canadian bank account
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.
Whose name a payout from this Virtual Account goes out under. Left out for a walletFiat destination or none.
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.
- US bank account
- IBAN bank account
- Canadian bank account
- Fiat wallet
How a deposit is returned to a bank returnDestination: only the rail. Left out with no return destination.
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.
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.
When a delete was accepted. Present only after a delete.