This guide walks you through how to get information about existing virtual accounts, or how to close existing virtual accounts.

Query Virtual Accounts

There are two ways to get virtual account information for your customers:

GET /virtual_accounts - lists all of your customers' virtual accounts. You can narrow your query using parameters such as participant_code
GET /virtual_accounts/{id} - Returns a single virtual account.

GET /virtual_accounts?participant_code=PART01&currency=USD&page=1&page_size=50

Example GET /virtual_accounts/{id} response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "participant_code": "PART01",
  "platform_code": "PLAT01",
  "provider_type": "CRB",
  "status": "PENDING",
  "currency": "USD",
  "bank_details": {
    "bank_account_number": "0000000001",
    "bank_routing_number": "123456789",
    "provider_account_id": "0000000001",
    "bank_name": "Cross River Bank"
  },
  "status_detail": {
    "code": "VA_CREATION_FAILED",
    "message": "zerohash was unable to open this virtual account. Contact zerohash support to request a new account.",
    "at": "2026-07-21T09:05:00.000Z"
  },
  "settlement_policy": {
    "type": "HOLD",
    "asset": "USDC",
    "external_account_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "created_at": "2026-07-20T14:22:00.000Z",
  "updated_at": "2026-07-20T14:22:00.000Z"
}

Close a Virtual Account

To close a Virtual Account, use the PATCH /virtual_accounts/{id}/close endpoint.

Example response when account closure is initiated:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CLOSING"
}

Example response when account is closed:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CLOSED"
}