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

{
  "customer": {
    "id": "<string>"
  },
  "id": "<string>",
  "status": "pending",
  "failure": {
    "code": "providerError",
    "message": "<string>",
    "retryable": true,
    "bankCode": "<string>"
  },
  "hold": {
    "code": "senderAttribution",
    "message": "<string>",
    "deadline": "2023-11-07T05:31:56Z",
    "match": {
      "address": "<string>",
      "network": "evm"
    }
  },
  "depositInstructions": {
    "bankUs": [
      {
        "bankName": "<string>",
        "bankAddress": "<string>",
        "accountNumber": "<string>",
        "supportedSources": [
          {
            "asset": "<string>",
            "rail": "ach"
          }
        ],
        "routingNumber": "<string>",
        "accountType": "<string>",
        "bic": "<string>",
        "memo": "<string>"
      }
    ]
  },
  "provider": "<string>",
  "destination": {
    "type": "walletCrypto",
    "asset": "<string>",
    "network": "<string>",
    "id": "<string>",
    "owner": {
      "kind": "counterparty",
      "id": "<string>",
      "name": "<string>"
    },
    "details": {
      "address": "<string>"
    }
  },
  "payout": {
    "rail": "ach",
    "instantRail": "rtp",
    "intraBankRail": "bookTransfer",
    "secCode": "ccd",
    "companyDiscretionaryData": "<string>"
  },
  "payoutOrigin": {
    "type": "bank",
    "id": "<string>",
    "accountHolder": "customer",
    "accountHolderName": "<string>"
  },
  "returnDestination": {
    "type": "bankUs",
    "asset": "usd",
    "id": "<string>",
    "instantRail": "rtp",
    "owner": {
      "kind": "counterparty",
      "id": "<string>",
      "name": "<string>"
    },
    "details": {
      "bankName": "<string>",
      "accountNumberLast4": "<string>",
      "routingNumber": "<string>",
      "accountType": "checking",
      "holderName": "<string>",
      "memo": "<string>"
    }
  },
  "returnPayout": {
    "rail": "ach",
    "instantRail": "rtp",
    "intraBankRail": "bookTransfer",
    "secCode": "ccd",
    "companyDiscretionaryData": "<string>"
  },
  "sponsorGas": true,
  "bankMemo": "<string>",
  "label": "<string>",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletionRequestedAt": "2023-11-07T05:31:56Z"
}

{
  "error": "InvalidRequest",
  "code": 10005,
  "msg": "the request is invalid",
  "cause": "<string>"
}

{
  "error": "DestinationRailNotAllowed",
  "code": 10184,
  "msg": "destination rail 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

{
  "customer": {
    "id": "<string>"
  },
  "id": "<string>",
  "status": "pending",
  "failure": {
    "code": "providerError",
    "message": "<string>",
    "retryable": true,
    "bankCode": "<string>"
  },
  "hold": {
    "code": "senderAttribution",
    "message": "<string>",
    "deadline": "2023-11-07T05:31:56Z",
    "match": {
      "address": "<string>",
      "network": "evm"
    }
  },
  "depositInstructions": {
    "bankUs": [
      {
        "bankName": "<string>",
        "bankAddress": "<string>",
        "accountNumber": "<string>",
        "supportedSources": [
          {
            "asset": "<string>",
            "rail": "ach"
          }
        ],
        "routingNumber": "<string>",
        "accountType": "<string>",
        "bic": "<string>",
        "memo": "<string>"
      }
    ]
  },
  "provider": "<string>",
  "destination": {
    "type": "walletCrypto",
    "asset": "<string>",
    "network": "<string>",
    "id": "<string>",
    "owner": {
      "kind": "counterparty",
      "id": "<string>",
      "name": "<string>"
    },
    "details": {
      "address": "<string>"
    }
  },
  "payout": {
    "rail": "ach",
    "instantRail": "rtp",
    "intraBankRail": "bookTransfer",
    "secCode": "ccd",
    "companyDiscretionaryData": "<string>"
  },
  "payoutOrigin": {
    "type": "bank",
    "id": "<string>",
    "accountHolder": "customer",
    "accountHolderName": "<string>"
  },
  "returnDestination": {
    "type": "bankUs",
    "asset": "usd",
    "id": "<string>",
    "instantRail": "rtp",
    "owner": {
      "kind": "counterparty",
      "id": "<string>",
      "name": "<string>"
    },
    "details": {
      "bankName": "<string>",
      "accountNumberLast4": "<string>",
      "routingNumber": "<string>",
      "accountType": "checking",
      "holderName": "<string>",
      "memo": "<string>"
    }
  },
  "returnPayout": {
    "rail": "ach",
    "instantRail": "rtp",
    "intraBankRail": "bookTransfer",
    "secCode": "ccd",
    "companyDiscretionaryData": "<string>"
  },
  "sponsorGas": true,
  "bankMemo": "<string>",
  "label": "<string>",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletionRequestedAt": "2023-11-07T05:31:56Z"
}

{
  "error": "InvalidRequest",
  "code": 10005,
  "msg": "the request is invalid",
  "cause": "<string>"
}

{
  "error": "DestinationRailNotAllowed",
  "code": 10184,
  "msg": "destination rail 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 payment memo delivered to the beneficiary's bank with the payout.

Honored on these rails, each with its own limit: - network: "ach" or "achSameDay": carried as the ACH addenda. NACHA characters only (uppercase letters, digits, space and .&()-+=':?@_#%), max 80. - network: "wire" or "rtp": ISO 20022 characters only (see the paymentMemo scalar), max 140. - A bankIban or bankCanada destination on swift: ISO 20022, max 140.

A memo outside its rail's characters or length is rejected with 422.

On a Quote, the memo is honored only on a walletFiat-source quote, or on a walletCrypto-source quote to a bankUs destination; any other corridor rejects it. A Virtual Account destination offers no rtp rail. On a Deposit Address the memo is read when each payout is built, so an edit applies only to payouts built after it, never to one already sent.

Where a memo is not honored — a rail with no remittance field, such as bankCanada's local leg, or a Quote corridor outside the two above — a non-empty memo is rejected with 422 MemoNotSupported, its cause carrying reason=unsupportedRail, rather than accepted and dropped. Sending null, omitting the field, or sending only whitespace is always accepted and means no memo of your own: the payout then carries the memo OMS composes for the rail, if any.

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 "rtp", 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. 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.

customer

object

required

The customer that owns this record.

Hide child attributes

customer.id

string

required

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

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

status

enum<string>

Current lifecycle status of the virtual account.

Available options:

pending,

active,

frozen,

closed,

deleted,

failed,

inactiveActionRequired,

deleting

failure

object

Why the virtual account failed. Present only when status is failed.

Hide child attributes

failure.code

enum<string>

required

What went wrong.

Available options:

providerError,

providerRejected,

providerTimeout,

expired,

systemError,

provisioningTimeout,

insufficientFunds,

providerAmountBelowMinimum,

limitExceeded,

outsideSellBounds,

outsideSellVelocityBounds,

unusableAmount,

unsupportedCorridor,

outgoingRailNotEnabled,

ssnNotVerified,

riskRejected,

cardDeclined,

bankSellDeclined,

payoutFailed,

priceMoved,

returningToSender,

returnedToSender,

returnFailed,

depositFailed,

attributionTimeout,

assetMismatch,

chainMismatch,

misattributedArrival,

depositAddressNotActive,

virtualAccountNotActive,

counterpartyArchived,

destinationUnavailable,

walletClaimed,

walletBoundToCustodialFlow,

projectSuspended,

memoInvalid,

cashDepositFailed,

noMatchingNetwork,

blockchainAddressInUse,

bankAccountInUse,

bankAccountRejected,

deletePendingTimeout,

providerAccountMissing,

cardInUse,

cardLimitReached,

countryProhibited,

countryNotSupported,

cardVerificationDeclined,

bankVerificationDeclined,

accountClosed,

accountFrozenByBank,

routingOrAccountNumberInvalid,

accountHolderDeceased,

accountDoesNotSupportTransfers,

payeeNameMismatch,

walletUnreachableOnNetwork,

billingAddressMismatch,

cardExpired,

cardClosedOrLostStolen,

pushToCardUnsupported,

cardDeclinedByIssuer

failure.message

string

required

A fixed, vendor-neutral sentence for code.

failure.retryable

boolean

required

Whether trying the same thing again can succeed.

failure.bankCode

string

The bank's own return code, only on an external account a bank return made invalid.

hold

object

What you must do for a virtual account in inactiveActionRequired: set a new destination. Present only in that status.

Hide child attributes

hold.code

enum<string>

required

Why the resource is held.

Available options:

senderAttribution,

payoutDestinationMissing

hold.message

string

required

A fixed, vendor-neutral sentence for code.

hold.deadline

string<date-time>

When the hold times out and the transaction fails. Only on senderAttribution.

hold.match

object

The sender's address and network to register to release the hold. Only on senderAttribution.

Hide child attributes

hold.match.address

string

required

The sender's on-chain address.

hold.match.network

enum<string>

required

The network family of the sender's address.

Available options:

evm,

solana,

tron

depositInstructions

object

Bank coordinates senders use to deposit into this Virtual Account. Left out until the provider has opened the account, so a pending Virtual Account carries none. Still present while it is deleting, and left out again once the account has ended, since a closed, failed or deleted Virtual Account can no longer receive a deposit. Capture it while the account is live if you need it for your own records.

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

object[]

The assets and rails this routing block accepts deposits on.

Hide child attributes

depositInstructions.bankUs.supportedSources.asset

string

required

Lowercase asset.

depositInstructions.bankUs.supportedSources.rail

enum<string>

required

The rail the deposit arrives on.

Available options:

ach,

achSameDay,

wire,

internationalWire,

rtp,

bookTransfer,

instant,

intraBank,

blockchain,

card,

cash

depositInstructions.bankUs.routingNumber

string

US ABA routing number; left out when the block has none.

depositInstructions.bankUs.accountType

string

US account type; left out when the block has none. Always "checking" when present.

depositInstructions.bankUs.bic

string

SWIFT/BIC code; present when supportedSources includes internationalWire.

depositInstructions.bankUs.memo

string

Reference senders must include when routing through a correspondent bank; left out when none is needed.

provider

string

The institution that issues and custodies this Virtual Account — currently "Erebor Bank, N.A." or "Cross River Bank". 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 name a payout is sent under, which is the payout transfer's originatorName 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 OMS cannot determine the institution.

destination

OMS wallet · object

The account deposits are paid out to. A bank account carries no rail and no ACH options; they are on payout.

Hide child attributes

destination.type

enum<string>

required

Available options:

walletCrypto

destination.asset

string

required

Lowercase asset.

destination.network

string

required

Lowercase blockchain.

destination.id

string

The wallet (wlt_); an older wallet keeps its original wlt_<uuid> id. Left out while a deposit's receiving wallet is 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.owner

object

Who owns an account that is not the resource's customer's.

Hide child attributes

destination.owner.kind

enum<string>

required

counterparty, or customer for another customer's account.

Available options:

counterparty,

customer

destination.owner.id

string

required

The counterparty (ctp_) or customer (cst_).

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

string

The counterparty's name. A customer's name is on the customer resource.

destination.details

object

OMS crypto wallet details.

Hide child attributes

destination.details.address

string

On-chain address.

payout

object

How a deposit is paid out to a bank or walletFiat destination: the rail and, on ach and achSameDay, the ACH options. Left out for a crypto destination.

Hide child attributes

payout.rail

enum<string>

required

The rail payouts move on from now on. Once the public-name cutover has passed, the same value as the rail of a payout transfer sent after it; a transfer sent before keeps its older name.

Available options:

ach,

achSameDay,

wire,

internationalWire,

rtp,

bookTransfer,

instant,

intraBank,

blockchain,

card,

cash

payout.instantRail

enum<string>

Only when rail is instant, the same value as the payout transfer's instantRail.

Available options:

rtp,

fednow

payout.intraBankRail

enum<string>

Only when rail is intraBank, the same value as the payout transfer's intraBankRail.

Available options:

bookTransfer,

crnow,

ereborRail

payout.secCode

enum<string>

ACH SEC code, only on ach and achSameDay. Derived from the destination owner's and the customer's entity type; left out while either is unknown. Never on a return.

Available options:

ccd,

ppd,

web

payout.companyDiscretionaryData

string

The ACH company discretionary data sent with each payout, only on ach and achSameDay and only when you set it. Never on a return.

payoutOrigin

object

Whose name a payout from this Virtual Account goes out under. Left out for a walletFiat destination or none.

Hide child attributes

payoutOrigin.type

enum<string>

required

Available options:

bank,

blockchain

payoutOrigin.id

string

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q.

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>

Whose legal identity the payment is sent under. Determined by OMS from the route's configuration — not a request field. Left out when OMS cannot determine it, and on destinations that have no sending legal identity (cash payouts, and crypto payouts outside a Deposit Address). A bank payout that goes out under the payment provider or the partner records that holder just before it is sent to the provider, and reports it only while a payout was or may have been created there; a send interrupted after the holder was recorded and before it went out has an unknown outcome and may report it. A failed send known to have created no payout at the provider, and a payout sent before holders were recorded whose holder could not be recovered afterwards, report the fallback value instead, which may differ from the holder actually used. The fallback value, also reported before a holder is recorded and for payouts that always go out under the customer's own name, is the holder the Deposit Address fixed for the destination type the transaction pays on a transaction created from a Deposit Address, and the value its route implies on any other.

Available options:

customer,

paymentProvider,

partner

payoutOrigin.accountHolderName

string

The legal name the payment is sent under, resolved from accountHolder — the customer's own legal name for customer, the owning customer's legal name for partner (for now; a partner-level name may replace it later), or the payment provider's name for paymentProvider, which differs between a bank origin ("Coinme Inc FBO its Customers") and a blockchain origin. This is what the recipient sees as the sender. Like accountHolder and unlike id, it is populated as soon as it is determinable, so it appears on Quote, Deposit Address and Virtual Account responses as well as Transactions. Left out whenever accountHolder is, and when the customer's name cannot be read at that moment.

returnDestination

US bank account · object

Where inbound fiat is sent back when its payout cannot be completed. It carries no rail; a bank return destination's rail is on returnPayout. Present only when you set one.

US bank account
IBAN bank account
Canadian bank account
Fiat wallet

Hide child attributes

returnDestination.type

enum<string>

required

Available options:

bankUs

returnDestination.asset

enum<string>

required

Lowercase asset.

Available options:

usd

returnDestination.id

string

The external account (ext_). Left out for a sender OMS has no record of.

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

returnDestination.instantRail

enum<string>

Only when network is instant.

Available options:

rtp,

fednow

returnDestination.owner

object

Who owns an account that is not the resource's customer's.

Hide child attributes

returnDestination.owner.kind

enum<string>

required

counterparty, or customer for another customer's account.

Available options:

counterparty,

customer

returnDestination.owner.id

string

required

The counterparty (ctp_) or customer (cst_).

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

returnDestination.owner.name

string

The counterparty's name. A customer's name is on the customer resource.

returnDestination.details

object

US bank account details.

Hide child attributes

returnDestination.details.bankName

string

returnDestination.details.accountNumberLast4

string

returnDestination.details.routingNumber

string

returnDestination.details.accountType

enum<string>

Bank account sub-type for US accounts.

Available options:

checking,

savings

returnDestination.details.holderName

string

The account holder: a counterparty's name, or the sender's name when the rail carries it.

returnDestination.details.memo

string

The free-text message that travelled with the money on this side's rail.

returnPayout

object

How a deposit is returned to a bank returnDestination: only the rail. Left out with no return destination.

Hide child attributes

returnPayout.rail

enum<string>

required

The rail payouts move on from now on. Once the public-name cutover has passed, the same value as the rail of a payout transfer sent after it; a transfer sent before keeps its older name.

Available options:

ach,

achSameDay,

wire,

internationalWire,

rtp,

bookTransfer,

instant,

intraBank,

blockchain,

card,

cash

returnPayout.instantRail

enum<string>

Only when rail is instant, the same value as the payout transfer's instantRail.

Available options:

rtp,

fednow

returnPayout.intraBankRail

enum<string>

Only when rail is intraBank, the same value as the payout transfer's intraBankRail.

Available options:

bookTransfer,

crnow,

ereborRail

returnPayout.secCode

enum<string>

ACH SEC code, only on ach and achSameDay. Derived from the destination owner's and the customer's entity type; left out while either is unknown. Never on a return.

Available options:

ccd,

ppd,

web

returnPayout.companyDiscretionaryData

string

The ACH company discretionary data sent with each payout, only on ach and achSameDay and only when you set it. Never on a return.

Whether OMS absorbs the on-chain gas cost for the destination delivery. Present only when true, the only value a create or update request accepts.

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.

deletionRequestedAt

string<date-time>

When a delete was accepted. Present only after a delete.

Overview

Move money

Routes

External Payment Methods

Platform

Read onchain data

Update a Virtual Account

Authorizations

Path Parameters

Body

Response