Update a Virtual Account

curl --request PATCH \
  --url https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": {
    "type": "bankUs",
    "details": {
      "id": "<string>",
      "asset": "usd",
      "memo": "<string>",
      "companyDiscretionaryData": "<string>"
    },
    "amount": "<string>"
  },
  "returnDestination": {
    "type": "bankUs",
    "id": "<string>"
  },
  "sponsorGas": true,
  "label": "<string>",
  "metadata": {}
}
'

import requests

url = "https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}"

payload = {
    "destination": {
        "type": "bankUs",
        "details": {
            "id": "<string>",
            "asset": "usd",
            "memo": "<string>",
            "companyDiscretionaryData": "<string>"
        },
        "amount": "<string>"
    },
    "returnDestination": {
        "type": "bankUs",
        "id": "<string>"
    },
    "sponsorGas": True,
    "label": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: {
      type: 'bankUs',
      details: {
        id: '<string>',
        asset: 'usd',
        memo: '<string>',
        companyDiscretionaryData: '<string>'
      },
      amount: '<string>'
    },
    returnDestination: {type: 'bankUs', id: '<string>'},
    sponsorGas: true,
    label: '<string>',
    metadata: {}
  })
};

fetch('https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'destination' => [
        'type' => 'bankUs',
        'details' => [
                'id' => '<string>',
                'asset' => 'usd',
                'memo' => '<string>',
                'companyDiscretionaryData' => '<string>'
        ],
        'amount' => '<string>'
    ],
    'returnDestination' => [
        'type' => 'bankUs',
        'id' => '<string>'
    ],
    'sponsorGas' => true,
    'label' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}"

	payload := strings.NewReader("{\n  \"destination\": {\n    \"type\": \"bankUs\",\n    \"details\": {\n      \"id\": \"<string>\",\n      \"asset\": \"usd\",\n      \"memo\": \"<string>\",\n      \"companyDiscretionaryData\": \"<string>\"\n    },\n    \"amount\": \"<string>\"\n  },\n  \"returnDestination\": {\n    \"type\": \"bankUs\",\n    \"id\": \"<string>\"\n  },\n  \"sponsorGas\": true,\n  \"label\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": {\n    \"type\": \"bankUs\",\n    \"details\": {\n      \"id\": \"<string>\",\n      \"asset\": \"usd\",\n      \"memo\": \"<string>\",\n      \"companyDiscretionaryData\": \"<string>\"\n    },\n    \"amount\": \"<string>\"\n  },\n  \"returnDestination\": {\n    \"type\": \"bankUs\",\n    \"id\": \"<string>\"\n  },\n  \"sponsorGas\": true,\n  \"label\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination\": {\n    \"type\": \"bankUs\",\n    \"details\": {\n      \"id\": \"<string>\",\n      \"asset\": \"usd\",\n      \"memo\": \"<string>\",\n      \"companyDiscretionaryData\": \"<string>\"\n    },\n    \"amount\": \"<string>\"\n  },\n  \"returnDestination\": {\n    \"type\": \"bankUs\",\n    \"id\": \"<string>\"\n  },\n  \"sponsorGas\": true,\n  \"label\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "virtualAccount",
  "customerId": "<string>",
  "customer": {
    "id": "<string>",
    "name": "<string>"
  },
  "status": "pending",
  "sourceToDestination": "cryptoToCrypto",
  "statusReason": "<string>",
  "source": {
    "asset": "<string>",
    "network": "<string>"
  },
  "depositInstructions": {
    "bankUs": [
      {
        "bankName": "<string>",
        "bankAddress": "<string>",
        "accountNumber": "<string>",
        "routingNumber": "<string>",
        "accountType": "<string>",
        "BIC": "<string>",
        "beneficiary": {
          "name": "<string>",
          "address": "<string>"
        },
        "memo": "<string>",
        "supportedSources": [
          {
            "asset": "<string>",
            "network": "<string>"
          }
        ]
      }
    ]
  },
  "provider": "<string>",
  "payoutOrigin": {
    "type": "bank",
    "id": "<string>",
    "accountHolder": "customer",
    "accountHolderName": "<string>"
  },
  "destination": {
    "type": "walletCrypto",
    "category": "crypto",
    "id": "<string>",
    "asset": "<string>",
    "network": "<string>",
    "displayName": "<string>",
    "party": {
      "relationship": "customer",
      "id": "<string>",
      "name": "<string>"
    },
    "memo": "<string>"
  },
  "returnDestination": {
    "type": "bankUs",
    "network": "ach",
    "id": "<string>"
  },
  "sponsorGas": true,
  "bankMemo": "<string>",
  "label": "<string>",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "failureReason": "provisioningTimeout",
  "deletionRequestedAt": "2023-11-07T05:31:56Z",
  "deletionRequestedBy": "<string>",
  "finalBalance": {
    "value": "<string>",
    "currency": "<string>",
    "display": "<string>"
  }
}

{
  "error": "InvalidRequest",
  "code": 10005,
  "msg": "at least one of destination, label, metadata, or returnDestination must be provided",
  "cause": "<string>"
}

{
  "error": "DestinationRailNotAllowed",
  "code": 10184,
  "msg": "destination rail %q is not enabled for this project",
  "cause": "<string>"
}

{
  "error": "CustodialWalletUnavailable",
  "code": 10304,
  "msg": "no usable custodial wallet is available for the requested asset and network",
  "cause": "<string>"
}

{
  "error": "Conflict",
  "code": 4000,
  "msg": "resource conflict",
  "cause": "<string>"
}

{
  "error": "AccountHolderUnsupported",
  "code": 10022,
  "msg": "destination.details.accountHolder must be customer",
  "cause": "<string>"
}

{
  "error": "Internal",
  "code": 10124,
  "msg": "internal error",
  "cause": "<string>"
}

{
  "error": "ServiceUnavailable",
  "code": 5003,
  "msg": "service unavailable",
  "cause": "<string>"
}

Virtual Accounts

Update a Virtual Account

Update a Virtual Account. Patchable fields: destination (re-point), sponsorGas, label, metadata; any other JSON key is rejected with 400. For an Erebor-vendored VA, re-pointing destination to a healthy External Account recovers it from inactiveActionRequired back to active. A Coinme-vendored VA has no PATCH-time recovery story: it only accepts a re-point while already active, and rejects anything else.

CustodialWalletUnavailableErrorResponse (10304) is declared here, not just on createVirtualAccount, because a walletCrypto re-point resolves the destination through the SAME resolver the create path uses. That resolver writes 10304 directly, so a walletCrypto PATCH re-point can surface it too.

PATCH

virtual-accounts

{virtualAccountId}

Update a Virtual Account

curl --request PATCH \
  --url https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": {
    "type": "bankUs",
    "details": {
      "id": "<string>",
      "asset": "usd",
      "memo": "<string>",
      "companyDiscretionaryData": "<string>"
    },
    "amount": "<string>"
  },
  "returnDestination": {
    "type": "bankUs",
    "id": "<string>"
  },
  "sponsorGas": true,
  "label": "<string>",
  "metadata": {}
}
'

import requests

url = "https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}"

payload = {
    "destination": {
        "type": "bankUs",
        "details": {
            "id": "<string>",
            "asset": "usd",
            "memo": "<string>",
            "companyDiscretionaryData": "<string>"
        },
        "amount": "<string>"
    },
    "returnDestination": {
        "type": "bankUs",
        "id": "<string>"
    },
    "sponsorGas": True,
    "label": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: {
      type: 'bankUs',
      details: {
        id: '<string>',
        asset: 'usd',
        memo: '<string>',
        companyDiscretionaryData: '<string>'
      },
      amount: '<string>'
    },
    returnDestination: {type: 'bankUs', id: '<string>'},
    sponsorGas: true,
    label: '<string>',
    metadata: {}
  })
};

fetch('https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'destination' => [
        'type' => 'bankUs',
        'details' => [
                'id' => '<string>',
                'asset' => 'usd',
                'memo' => '<string>',
                'companyDiscretionaryData' => '<string>'
        ],
        'amount' => '<string>'
    ],
    'returnDestination' => [
        'type' => 'bankUs',
        'id' => '<string>'
    ],
    'sponsorGas' => true,
    'label' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}"

	payload := strings.NewReader("{\n  \"destination\": {\n    \"type\": \"bankUs\",\n    \"details\": {\n      \"id\": \"<string>\",\n      \"asset\": \"usd\",\n      \"memo\": \"<string>\",\n      \"companyDiscretionaryData\": \"<string>\"\n    },\n    \"amount\": \"<string>\"\n  },\n  \"returnDestination\": {\n    \"type\": \"bankUs\",\n    \"id\": \"<string>\"\n  },\n  \"sponsorGas\": true,\n  \"label\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": {\n    \"type\": \"bankUs\",\n    \"details\": {\n      \"id\": \"<string>\",\n      \"asset\": \"usd\",\n      \"memo\": \"<string>\",\n      \"companyDiscretionaryData\": \"<string>\"\n    },\n    \"amount\": \"<string>\"\n  },\n  \"returnDestination\": {\n    \"type\": \"bankUs\",\n    \"id\": \"<string>\"\n  },\n  \"sponsorGas\": true,\n  \"label\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.polygon.technology/v0.13/virtual-accounts/{virtualAccountId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination\": {\n    \"type\": \"bankUs\",\n    \"details\": {\n      \"id\": \"<string>\",\n      \"asset\": \"usd\",\n      \"memo\": \"<string>\",\n      \"companyDiscretionaryData\": \"<string>\"\n    },\n    \"amount\": \"<string>\"\n  },\n  \"returnDestination\": {\n    \"type\": \"bankUs\",\n    \"id\": \"<string>\"\n  },\n  \"sponsorGas\": true,\n  \"label\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "object": "virtualAccount",
  "customerId": "<string>",
  "customer": {
    "id": "<string>",
    "name": "<string>"
  },
  "status": "pending",
  "sourceToDestination": "cryptoToCrypto",
  "statusReason": "<string>",
  "source": {
    "asset": "<string>",
    "network": "<string>"
  },
  "depositInstructions": {
    "bankUs": [
      {
        "bankName": "<string>",
        "bankAddress": "<string>",
        "accountNumber": "<string>",
        "routingNumber": "<string>",
        "accountType": "<string>",
        "BIC": "<string>",
        "beneficiary": {
          "name": "<string>",
          "address": "<string>"
        },
        "memo": "<string>",
        "supportedSources": [
          {
            "asset": "<string>",
            "network": "<string>"
          }
        ]
      }
    ]
  },
  "provider": "<string>",
  "payoutOrigin": {
    "type": "bank",
    "id": "<string>",
    "accountHolder": "customer",
    "accountHolderName": "<string>"
  },
  "destination": {
    "type": "walletCrypto",
    "category": "crypto",
    "id": "<string>",
    "asset": "<string>",
    "network": "<string>",
    "displayName": "<string>",
    "party": {
      "relationship": "customer",
      "id": "<string>",
      "name": "<string>"
    },
    "memo": "<string>"
  },
  "returnDestination": {
    "type": "bankUs",
    "network": "ach",
    "id": "<string>"
  },
  "sponsorGas": true,
  "bankMemo": "<string>",
  "label": "<string>",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "failureReason": "provisioningTimeout",
  "deletionRequestedAt": "2023-11-07T05:31:56Z",
  "deletionRequestedBy": "<string>",
  "finalBalance": {
    "value": "<string>",
    "currency": "<string>",
    "display": "<string>"
  }
}

{
  "error": "InvalidRequest",
  "code": 10005,
  "msg": "at least one of destination, label, metadata, or returnDestination must be provided",
  "cause": "<string>"
}

{
  "error": "DestinationRailNotAllowed",
  "code": 10184,
  "msg": "destination rail %q is not enabled for this project",
  "cause": "<string>"
}

{
  "error": "CustodialWalletUnavailable",
  "code": 10304,
  "msg": "no usable custodial wallet is available for the requested asset and network",
  "cause": "<string>"
}

{
  "error": "Conflict",
  "code": 4000,
  "msg": "resource conflict",
  "cause": "<string>"
}

{
  "error": "AccountHolderUnsupported",
  "code": 10022,
  "msg": "destination.details.accountHolder must be customer",
  "cause": "<string>"
}

{
  "error": "Internal",
  "code": 10124,
  "msg": "internal error",
  "cause": "<string>"
}

{
  "error": "ServiceUnavailable",
  "code": 5003,
  "msg": "service unavailable",
  "cause": "<string>"
}

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 or bank 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, a bank EA, or a walletFiat fiat wallet — same kind as the current destination: a cross-kind switch involving walletFiat is rejected with 422 destinationTypeSwitchNotSupported). Re-validated exactly like create; walletCrypto is NOT currently supported — 422 destinationWalletCryptoNotSupported.

Hide child attributes

destination.type

enum<string>

required

Type discriminator.

Available options:

bankUs

destination.details

object

required

Hide child attributes

destination.details.id

string

required

US bank ExternalAccount ID (ext_ prefix).

destination.details.asset

enum<string>

required

Canonical asset identifier.

Available options:

usd

destination.details.network

enum<string>

required

Rail to deliver on.

Available options:

ach,

achSameDay,

wire

destination.details.memo

string | null

Optional customer-supplied payment memo delivered to the beneficiary's bank.

HONORED TODAY ON: a Deposit Address bankUs destination with network: "wire" or network: "rtp" (create and update). The stored value replaces — it does not append to — the memo OMS would otherwise generate for every outbound Fedwire/RTP payout from that deposit address. Send null (or omit it on an update that replaces destination) to restore the generated memo. Because the memo is read when each payout is built, an edit affects only future payouts, never one already in flight.

REJECTED EVERYWHERE ELSE, with 422 memoNotSupported: this field is shared by the Quote and Virtual Account request surfaces (create and update), and by a deposit-address bankUs destination on the ach / achSameDay rails. A non-empty memo on any of those is refused rather than accepted and dropped — a silently ignored field on a money path gives the caller a success response while the payout carries the generated memo. Sending null, omitting the field, or sending only whitespace is always accepted (it means "no override"). Each rejected surface becomes accepting as its support ships; relaxing a 422 into an accepted value never breaks a caller, so no client needs to change when that happens.

The error body's details.reason tells apart a temporary gap from a permanent one: "notImplemented" means this surface/rail will accept the field once support for it ships (every current rejection above is this case); "unsupportedRail" would mean the field is not a concept on this rail and never will be (e.g. the shared model also carries fields that are rail-specific by design, like ACH's companyDiscretionaryData on a wire destination) — retry the first after a release, never the second.

Maximum string length: 140

Pattern: ^[A-Za-z0-9 /?:().,'+\-]*$

destination.details.companyDiscretionaryData

string | null

Optional ACH-only field for the originator's internal use (NACHA batch header). See the companyDiscretionaryData scalar doc. Honored only when network is "ach" or "achSameDay"; 422 memoNotSupported on "wire" (and, on a Deposit Address destination, on "rtp" too — rejected with the same code despite being a real rail, because the field itself is an ACH-only concept).

Maximum string length: 20

Pattern: ^[A-Z0-9 &\-\.\$*\/#@%]*$

destination.amount

string

Wire-safe decimal string for financial float values (USD amounts, percentages).

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.

US bank account
IBAN bank account
Canadian bank account
Fiat wallet

Hide child attributes

returnDestination.type

enum<string>

required

Type discriminator.

Available options:

bankUs

returnDestination.network

enum<string>

required

Rail to return on.

Available options:

ach,

achSameDay,

wire

returnDestination.id

string

required

US bank ExternalAccount id (ext_ prefix).

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.

Hide child attributes

metadata.{key}

string

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.

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})$

customer

object

Display-safe summary of the owning customer (customer.id equals customerId). Returned on list and detail responses.

Hide child attributes

customer.id

string

required

The OMS customer id (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})$

customer.name

string

required

Customer display name.

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 or walletFiat destination (inbound USD forwarded onward — the same token for both; walletFiat introduces no new corridor).

Available options:

cryptoToCrypto,

cryptoToCash,

cryptoToFiatAccount,

cashToCrypto,

fiatAccountToCrypto,

fiatAccountToFiatAccount

statusReason

string

Human-readable explanation of the current status.

source

object

Expected inbound rail detail.

Hide child attributes

source.asset

string

required

Fixed for Alpha: "usd".

source.network

string

required

Fixed for Alpha: "usBank".

depositInstructions

object

Bank coordinates senders use to deposit into this Virtual Account. Null until the provider has opened the account, so a pending Virtual Account carries none.

Hide child attributes

depositInstructions.bankUs

object[]

Hide child attributes

depositInstructions.bankUs.bankName

string

required

depositInstructions.bankUs.bankAddress

string

required

depositInstructions.bankUs.accountNumber

string

required

depositInstructions.bankUs.routingNumber

string | null

required

US domestic only; null for SWIFT.

depositInstructions.bankUs.accountType

string | null

required

US domestic only; null for SWIFT. Always "checking" when present.

depositInstructions.bankUs.BIC

string | null

required

SWIFT only; null for US domestic.

depositInstructions.bankUs.beneficiary

object

required

Who senders should address the deposit to — the party the funds are ultimately credited to. On a SWIFT routing block this is the holding bank itself, and the customer is named in that block's memo; on a US domestic block it is the customer. Response-only, determined by OMS and not configurable on create. address is a single formatted display line, e.g. "6 Acme Way, Bentonville, AR 72712 US".

Hide child attributes

depositInstructions.bankUs.beneficiary.name

string

required

depositInstructions.bankUs.beneficiary.address

string

required

depositInstructions.bankUs.memo

string | null

required

SWIFT only; null for US domestic. OMS-generated: "FFC ".

depositInstructions.bankUs.supportedSources

object[]

Asset/network pairs this routing block accepts deposits for.

Hide child attributes

depositInstructions.bankUs.supportedSources.asset

string

required

depositInstructions.bankUs.supportedSources.network

string

required

provider

string

The institution that issues and custodies this Virtual Account — currently "Erebor Bank, N.A." or "Coinme Inc.". 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 entity an outbound forward is sent under — that is payoutOrigin.accountHolderName, which is set by whoever executes the payout 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 the vendor is unrecognized.

payoutOrigin

object

Where the onward forward of an inbound deposit is sent from, and whose legal identity it goes out under. Response-only, derived from the destination type and the issuing institution. A bank destination renders the bank arm; a crypto-wallet destination renders the blockchain arm with a null accountHolder, since a crypto payout has no sending legal identity. Absent for a walletFiat destination, whose delivery is an internal ledger movement rather than a payout. accountHolder and accountHolderName are also null whenever OMS cannot name the issuing institution.

Hide child attributes

payoutOrigin.type

enum<string>

required

Available options:

bank,

blockchain

payoutOrigin.id

string | null

required

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

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})$

payoutOrigin.accountHolder

enum<string> | null

required

Whose legal identity the payment is sent under. Determined by OMS from the route's configuration — not a request field. Null for destinations that have no sending legal identity (crypto and cash payouts).

Available options:

customer,

paymentProvider

payoutOrigin.accountHolderName

string | null

required

The legal name the payment is sent under, resolved from accountHolder — the customer's own legal name for customer, or "Coinme Inc FBO its Customers" for paymentProvider. This is what the recipient's bank shows on the credit. Like accountHolder and unlike id, it is populated as soon as it is determinable, so it appears on Quote and Deposit Address responses as well as Transactions. Null whenever accountHolder is null.

destination

OMS wallet · object

V0.10: unified side shape.

Hide child attributes

destination.type

enum<string>

required

Type discriminator.

Available options:

walletCrypto

destination.category

enum<string>

required

High-level grouping: fiatAccount for bank or card accounts, crypto for wallets.

Available options:

crypto

destination.id

string | null

required

OMS wallet ID (wlt_ prefix). Dereference via GET /wallets/{id}. Null while a deposit is still in flight and the wallet it lands in has not resolved yet.

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})$

destination.asset

string

required

Canonical asset identifier.

destination.network

string

required

Network identifier.

destination.displayName

string

required

Opaque, render-only summary for list/detail display. Never a full account number/IBAN/PAN.

destination.party

object

Structured identity of who is on this side.

Hide child attributes

destination.party.relationship

enum<string>

required

Which kind of party this is.

Available options:

customer,

otherCustomer,

externalRegistered,

externalUnregistered

destination.party.id

string | null

required

cst_ for customer/otherCustomer; ctp_ for externalRegistered; null for externalUnregistered.

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})$

destination.party.name

string | null

required

Display name. Null only when genuinely unknown (an unattributed external sender).

destination.memo

string

Free-text message that travelled with the transfer on this side's rail. Never populated on this instrument — no rail behind it carries a message — so the key is always absent. A memo appears only on the bank arms (bankUs, bankIban, bankCanada).

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

US bank account
IBAN bank account
Canadian bank account
Fiat wallet

Hide child attributes

returnDestination.type

enum<string>

required

Type discriminator.

Available options:

bankUs

returnDestination.network

enum<string>

required

Rail to return on.

Available options:

ach,

achSameDay,

wire

returnDestination.id

string

required

US bank ExternalAccount id (ext_ prefix).

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.

Hide child attributes

metadata.{key}

string

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,

coinmeDeclined

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.

Hide child attributes

finalBalance.value

string

required

Amount in fiat minor units (e.g. cents).

finalBalance.currency

string

required

ISO 4217 currency code.

finalBalance.display

string

required

Human-readable rendering (e.g. "12.34 USD").

Overview

Move money

Routes

External Payment Methods

Platform

Update a Virtual Account

Authorizations

Path Parameters

Body

Response