Skip to main content
PATCH
Update a Virtual Account

Authorizations

Authorization
string
header
required

Token from POST /auth/token

Path Parameters

virtualAccountId
string
required

Virtual Account ID (va_ prefix).

Body

application/json

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.

destination
US bank account · object

Re-point the VA destination (walletExternal by registered EA id, or walletOms by wallet id). Re-validated exactly like create.

returnDestination
US bank account · object

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.

sponsorGas
boolean
default:true

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

label
string

Partner display label.

metadata
object

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

Response

200 - application/json

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.

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})$
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 destination (inbound USD forwarded onward).

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

Null until Erebor provisions the DDA (DEPOSIT_ACCOUNT.OPEN).

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
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.