> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle Virtual Account Webhooks

> Subscribe to the webhook events of virtual accounts and their deposits, and act on each one

This guide sets up your server to receive the webhook events of virtual accounts and to act on each one. Crossmint sends two kinds of events. One event reports a change in the status of an account. The order events report each step of a deposit, because every bank transfer into an account is an order.

## Prerequisites

* **Account**: a virtual account, opened as in [Open a Virtual Account](https://docs.crossmint.com/virtual-accounts/guides/open-a-virtual-account.md).
* **Webhook endpoint**: a public HTTPS endpoint on your server that verifies the signature of each delivery, as described in [Webhooks](https://docs.crossmint.com/payments/advanced/webhooks.md).
* **API Key**: a server API key with the `virtual-accounts.read` and `orders.read` scopes, to read the account or the order after each event. In staging, all scopes are included by default.

## Subscribe to the Events

In the Crossmint Console, add your endpoint and subscribe it to the events below, as described in [Webhooks](https://docs.crossmint.com/payments/advanced/webhooks.md#setting-up-webhooks). Every delivery is signed, and a failed delivery is retried.

| Event | When |
| :- | :- |
| `virtual_accounts.status.updated` | The `status` or the `statusReason` of an account changes |
| `orders.quote.created` | A transfer arrives and its order is created |
| `orders.payment.succeeded` | Crossmint accepted the deposit |
| `orders.payment.in_review` | The deposit goes into review |
| `orders.payment.failed` | The deposit is refused. It can also follow `orders.payment.succeeded` |
| `orders.delivery.initiated` | The stablecoin delivery starts |
| `orders.delivery.completed` | The delivery is confirmed onchain |
| `orders.delivery.failed` | The delivery fails |
| `orders.payment.refund_sent` | The return is sent to the sender |
| `orders.payment.refund_failed` | The return fails, or the sender's bank sends it back |

## Handle Account Status Changes

`virtual_accounts.status.updated` fires each time the `status` of an account changes, and when the `statusReason` changes while the status stays. See [Account Statuses](https://docs.crossmint.com/virtual-accounts/guides/manage-virtual-accounts.md#account-statuses) for every value.

```json virtual_accounts.status.updated theme={null}
{
    "id": "virtual-account-status-7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35-2",
    "type": "virtual_accounts.status.updated",
    "data": {
        "sequence": 2,
        "previousStatus": "active",
        "virtualAccount": {
            "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
            "status": "suspended",
            "statusReason": "compliance-suspended"
        }
    },
    "timestamp": 1794931200000
}
```

| Field | Description |
| :- | :- |
| `id` | `virtual-account-status-<virtualAccountId>-<sequence>`. The same on every retry |
| `data.sequence` | Starts at 1 for each account and grows by one with each event of that account |
| `data.previousStatus` | The status before this change |
| `data.virtualAccount` | The `virtualAccountId`, the new `status`, and the new `statusReason` |
| `timestamp` | Milliseconds since the epoch |

The event carries no bank details, wallet, or label. When it arrives, read the account with `GET /api/2026-09-16/virtual-accounts/{virtualAccountId}`, and show the bank details as a way to add funds only when `status` is `active`.

No event fires for the create response, for a repeated create, or for a `DELETE` that changes nothing. An account that is `active` in the create response sends no event.

## Handle Deposit Events

Every order event is delivered as `actionId`, `type`, and `data`. `data` is the full order, identical to the [Get Order](https://docs.crossmint.com/onramp/api-reference/get-order.md) response, including the deposit fields `payment.payer.virtualAccountId`, `payment.reference`, and `payment.sender`.

```json orders.payment.succeeded theme={null}
{
    "actionId": "b2959ca5-65e4-466a-bd26-1bd05cb4f837",
    "type": "orders.payment.succeeded",
    "data": {
        "orderId": "b2959ca5-65e4-466a-bd26-1bd05cb4f837",
        "phase": "delivery",
        "locale": "en-US",
        "lineItems": [
            {
                "chain": "solana",
                "executionMode": "exact-in",
                "executionParams": {
                    "mode": "exact-in",
                    "amount": "200.00"
                },
                "quote": {
                    "status": "valid",
                    "totalPrice": {
                        "amount": "200.00",
                        "currency": "eur"
                    }
                },
                "delivery": {
                    "status": "in-progress",
                    "recipient": {
                        "locator": "solana:7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
                        "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px"
                    }
                }
            }
        ],
        "quote": {
            "status": "valid",
            "totalPrice": {
                "amount": "200.00",
                "currency": "eur"
            }
        },
        "payment": {
            "status": "completed",
            "method": "bank-transfer",
            "currency": "eur",
            "receiptEmail": "jane@example.com",
            "received": {
                "amount": "200.00",
                "currency": "eur"
            },
            "payer": {
                "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35"
            },
            "reference": "Invoice 123",
            "sender": {
                "name": "JANE DOE",
                "institutionName": "BBVA",
                "accountLast4": "4821",
                "rail": "sct-inst",
                "classification": "first-party"
            }
        }
    }
}
```

The events of a deposit arrive in a set order for each outcome. Every deposit starts with `orders.quote.created`.

| Deposit | Events after `orders.quote.created` |
| :- | :- |
| Delivered | `orders.payment.succeeded` `orders.delivery.initiated` `orders.delivery.completed` |
| Refused and sent back | `orders.payment.failed` `orders.payment.refund_sent` |
| Accepted, then sent back before delivery | `orders.payment.succeeded` `orders.payment.failed` `orders.payment.refund_sent` |
| In review, then delivered | `orders.payment.in_review` `orders.payment.succeeded` `orders.delivery.initiated` `orders.delivery.completed` |
| Return did not go through | `orders.payment.failed` `orders.payment.refund_failed` |

When an order event arrives, update the deposit in your app from the order. See [Deposit States](https://docs.crossmint.com/virtual-accounts/guides/track-deposits.md#deposit-states) for the fields of the order at each step.

## Make Your Handler Reliable

* **Return a 2xx status quickly.** Your server must answer with a 2xx HTTP status so the webhook is marked as delivered. Do the work after you answer.
* **Deduplicate.** A retried delivery carries the same `svix-id` header. Process each `svix-id` once.
* **Read after every event.** When an event arrives, read the account or the order from the API and use that response, not the event payload, as the current state.
* **Expect events out of order.** For account events, use `sequence` so older data never overwrites newer state.
* **Do not treat acceptance as final.** `orders.payment.succeeded` means Crossmint accepted the deposit. A deposit can still go back before it is delivered. After delivery, nothing goes back.
* **Expect repeats of return events.** A second `orders.payment.refund_sent` can arrive for the same order, when an earlier return did not go through.
* **Accept new fields.** Do not validate payloads strictly. Crossmint can add fields and values to these events.

## Next Steps

> [card] [Track Deposits](https://docs.crossmint.com/virtual-accounts/guides/track-deposits.md)
>
> The states and fields of each deposit

> [card] [Test in Staging](https://docs.crossmint.com/virtual-accounts/guides/test-in-staging.md)
>
> Simulate deposits and receive every event
