Sign in

v1

latestOpenAPI 3.0.32026-07-2650226215.9 KB
VirtualAccount

Create a Virtual Account

Create a Virtual Account for a customer. Partner must have virtual_account_provider configured.

post/virtual-accounts

Headers

Idempotency-Keystring required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Request body

customerIdstring required

Owning customer (cus_… or legacy public id).

accountHolderstring required

Closed for Alpha: must be "customer" (additive later - bankMexico / more accountHolders land within 6-12 months).

typestring required

Must be "bankUs".

sponsorGasboolean

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

bankMemostring

Optional wire/ACH memo the customer can include.

labelstring

Partner display label.

metadataobject

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

Example request

{
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "type": "bankUs",
  "accountHolder": "customer",
  "source": {
    "asset": "usd",
    "network": "ach"
  },
  "destination": {
    "type": "walletOms",
    "details": {
      "id": "wlt_5h4jzzpr9xre3bamd9ca7qyghn",
      "asset": "usdc",
      "network": "polygon"
    }
  },
  "sponsorGas": true,
  "label": "Alice USD deposit account"
}

Response

The request has succeeded and a new resource has been created as a result.

idstring

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

object'virtualAccount'

Resource type discriminator. Always "virtualAccount".

customerIdstring

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

status'pending' | 'active' | 'frozen' | 'closed' | 'deleted' | 'failed' | 'inactiveActionRequired'

Lifecycle of a Virtual Account. pending: awaiting bank provisioning. active: accepting deposits. frozen: deposits held by compliance. inactiveActionRequired: destination unusable - re-point destination to recover. closed: permanently disabled. deleted: close flow finalized. failed: provisioning failed.

statusReasonstring

Human-readable explanation of the current status.

sponsorGasboolean

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

bankMemostring

Wire/ACH memo the customer can include with deposits.

labelstring

Partner display label.

metadataobject

Free-form key-value pairs supplied at creation or update.

createdAtstring date-time

When the virtual account was created.

updatedAtstring date-time

When the virtual account was last updated.

failureReason'provisioningTimeout' | 'systemError' | 'ereborRejected' | 'deletePendingTimeout'

Closed enum stamped by failVA when a VA flips to terminal failed state.

deletionRequestedAtstring date-time

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

deletionRequestedBystring

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