Virtual Account Status Updates

Platforms using the Virtual Accounts product can subscribe to webhooks to receive real-time updates when a customer's virtual account changes status. There are the following scenarios:

Event	Scenario	Description	Status	`status_detail.code`
virtual_account.created	Created	The virtual account has been successfully created and is active.	ACTIVE	n.a
virtual_account.closed	Closed	The virtual account has been closed.	CLOSED	n.a
virtual_account.blocked	Blocked	zerohash has blocked the virtual account; it can no longer receive deposits.	BLOCKED	VA_BLOCKED
virtual_account.failed	Failed - Creation declined	zerohash could not open the virtual account for the account holder.	FAILED	VA_CREATION_DECLINED
virtual_account.failed	Failed - Creation failed	zerohash was unable to open the virtual account due to an internal or provider-side error.	FAILED	VA_CREATION_FAILED
virtual_account.suspended	Suspended	zerohash has temporarily suspended the virtual account pending review.	SUSPENDED	VA_SUSPENDED
virtual_account.deposit_received	Deposit Received	A deposit has landed in a virtual account configured with the `HOLD` settlement policy. This is a terminal state - funds are credited to the account balance and no settlement events follow.	n.a. (transaction-level event)	n.a
virtual_account.settlement_initiated	Settlement Initiated	For accounts configured with `AUTO_CONVERT_AND_WITHDRAW`, conversion of the deposited funds and payout to the configured external account has begun.	n.a. (transaction-level event)	n.a
virtual_account.settlement_completed	Settlement Completed	For accounts configured with `AUTO_CONVERT_AND_WITHDRAW`, the conversion and payout have completed successfully.	n.a. (transaction-level event)	n.a
virtual_account.settlement_failed	Settlement Failed	For accounts configured with `AUTO_CONVERT_AND_WITHDRAW`, the conversion or payout leg failed.	n.a. (transaction-level event)	n.a

Field Definitions

Field	Description	Always Present?	Type
virtual_account_id	zerohash-generated unique identifier for the virtual account	Yes	string
participant_code	End customer's participant code	Yes	string
platform_code	The Participant code associated with the Platform	Yes	string
provider_type	The banking provider backing the virtual account. Currently only `CRB` is supported.	Yes	string
status	The current status of the virtual account. One of `ACTIVE`, `CLOSED`, `BLOCKED`, `FAILED`.	Yes	string
bank_details	The virtual account's bank details.	No - only present when status = `ACTIVE` (Created event)	string
bank_details.account_number	The virtual account's account number	No - only present when `bank_details` is present	string
bank_details.routing_number	The virtual account's routing number	No - only present when `bank_details` is present	string
bank_details.provider_account_id	The banking provider's internal identifier for the account	No - only present when `bank_details` is present	string
status_detail	Additional context on why the account entered its current status	No - only present when status = `BLOCKED` or `FAILED`, and a code has been recorded	string
status_detail.code	Stable, machine-readable code describing the reason. One of `VA_BLOCKED`, `VA_CREATION_DECLINED`, `VA_CREATION_FAILED`, or an unclassified fallback code.	No - only present when status = `BLOCKED` or `FAILED`, and a code has been recorded	string
status_detail.message	Human-readable description of the code	No - only present when status = `BLOCKED` or `FAILED`, and a code has been recorded	string
status_detail.at	Timestamp the status detail was recorded	No - only present when status = `BLOCKED` or `FAILED`, and a code has been recorded	timestamp
created_at	Timestamp the virtual account was created	Yes	timestamp
updated_at	Timestamp the virtual account was last updated	Yes	timestamp

Payloads

Created

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "provider_type": "CRB",
  "status": "ACTIVE",
  "bank_details": {
    "account_number": "1234567890",
    "routing_number": "021000021",
    "provider_account_id": "crb_ac_9f13e2"
  },
  "created_at": "2026-08-20T14:32:01Z",
  "updated_at": "2026-08-20T14:32:01Z"
}

Closed

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "provider_type": "CRB",
  "status": "CLOSED",
  "created_at": "2026-08-20T14:32:01Z",
  "updated_at": "2026-08-25T09:10:44Z"
}

Blocked

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "provider_type": "CRB",
  "status": "BLOCKED",
  "status_detail": {
    "code": "VA_BLOCKED",
    "message": "zerohash has blocked this virtual account and it can no longer receive deposits. Contact zerohash support for next steps.",
    "at": "2026-08-25T09:10:44Z"
  },
  "created_at": "2026-08-20T14:32:01Z",
  "updated_at": "2026-08-25T09:10:44Z"
}

Failed - Creation declined

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "provider_type": "CRB",
  "status": "FAILED",
  "status_detail": {
    "code": "VA_CREATION_DECLINED",
    "message": "zerohash could not open this virtual account for the account holder. Contact zerohash support for next steps.",
    "at": "2026-08-20T14:32:01Z"
  },
  "created_at": "2026-08-20T14:32:01Z",
  "updated_at": "2026-08-20T14:32:01Z"
}

Failed - Creation failed

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "provider_type": "CRB",
  "status": "FAILED",
  "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-08-20T14:32:01Z"
  },
  "created_at": "2026-08-20T14:32:01Z",
  "updated_at": "2026-08-20T14:32:01Z"
}

Deposit Received (HOLD accounts)

Fires when a deposit lands in a HOLD-policy virtual account. Terminal state - no settlement events follow.

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "transaction_id": "vat_3d9f6b2c1a8e4f7d",
  "type": "DEPOSIT",
  "status": "RECEIVED",
  "amount": "2500.00",
  "currency": "USD",
  "reference": "INV-10432",
  "created_at": "2026-08-25T09:10:44Z"
}

Settlement Initiated (AUTO_CONVERT_AND_WITHDRAW accounts)

Fires when an incoming deposit begins automatic conversion and payout to the account's configured external account. Note there is no preceding deposit_received event for this settlement policy.

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "transaction_id": "vat_9c4e1f7a2b6d3e8f",
  "type": "DEPOSIT",
  "status": "SETTLEMENT_INITIATED",
  "amount": "2500.00",
  "currency": "USD",
  "reference": "INV-10432",
  "created_at": "2026-08-25T09:10:44Z"
}

Settlement Completed (AUTO_CONVERT_AND_WITHDRAW accounts)

Fires once the conversion and payout have completed successfully.

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "transaction_id": "vat_9c4e1f7a2b6d3e8f",
  "type": "DEPOSIT",
  "status": "SETTLEMENT_COMPLETED",
  "amount": "2500.00",
  "currency": "USD",
  "reference": "INV-10432",
  "created_at": "2026-08-25T09:10:44Z",
  "settled_at": "2026-08-25T09:12:03Z"
}

Settlement Failed (AUTO_CONVERT_AND_WITHDRAW accounts)

Fires if the conversion or payout leg fails.

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "transaction_id": "vat_9c4e1f7a2b6d3e8f",
  "type": "DEPOSIT",
  "status": "SETTLEMENT_FAILED",
  "amount": "2500.00",
  "currency": "USD",
  "reference": "INV-10432",
  "created_at": "2026-08-25T09:10:44Z"
}

Suspended

Fires if a virtual account is temporarily suspended (distinct from a permanent block), pausing deposit activity pending review.

{
  "virtual_account_id": "va_8f2c1a9e4b7d4e0a",
  "participant_code": "CUST01",
  "platform_code": "PLAT01",
  "provider_type": "CRB",
  "status": "SUSPENDED",
  "status_detail": {
    "code": "VA_SUSPENDED",
    "message": "zerohash has temporarily suspended this virtual account pending review.",
    "at": "2026-08-25T09:10:44Z"
  },
  "created_at": "2026-08-20T14:32:01Z",
  "updated_at": "2026-08-25T09:10:44Z"
}