POpolygon-technology
VirtualAccount

Create a Virtual Account

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

post/virtual-accounts

Request

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.

Changes

No recorded changes to this operation across all 1 revision of this API.