Update a Virtual Account
Update a Virtual Account. Patchable fields: destination (re-point),
sponsorGas, label, metadata; any other JSON key is rejected with
400. Re-pointing destination to a healthy External Account recovers a
VA from inactiveActionRequired back to active.
Authorizations
Token from POST /auth/token
Path Parameters
Virtual Account ID (va_ prefix).
Body
Partial update payload for a Virtual Account. The patchable fields are
destination (re-point to a different walletExternal / walletOms target),
returnDestination (re-point or clear the fiat return destination),
sponsorGas, label, and metadata. Any additional key in the JSON body
is rejected with 400 by the handler (strict whitelist).
Re-pointing destination to a healthy External Account recovers a VA from
inactiveActionRequired back to active; a re-point on an already
active VA updates the target without a status transition.
Re-point the VA destination (walletExternal by registered EA id, or walletOms by wallet id). Re-validated exactly like create.
- US bank account
- IBAN bank account
- Canadian bank account
- OMS wallet
- External wallet (registered)
Re-point or clear the fiat return destination (v0.11-8). Re-validated
exactly like create; an explicit null in the JSON body clears a
previously set return destination.
- 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; accepted for
forward-compatibility.
Partner display label.
Free-form key-value pairs stored on the resource and echoed back on reads.
Response
The request has succeeded.
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})$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 destination (inbound USD forwarded
onward).
cryptoToCrypto, cryptoToCash, cryptoToFiatAccount, cashToCrypto, fiatAccountToCrypto, fiatAccountToFiatAccount Human-readable explanation of the current status.
Expected inbound rail detail.
Null until Erebor provisions the DDA (DEPOSIT_ACCOUNT.OPEN).
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 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.