Prerequisites
- Account: a virtual account, opened as in Open a Virtual Account.
- Webhook endpoint: a public HTTPS endpoint on your server that verifies the signature of each delivery, as described in Webhooks.
- API Key: a server API key with the
virtual-accounts.readandorders.readscopes, 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. Every delivery is signed, and a failed delivery is retried.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 for every value.
virtual_accounts.status.updated
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 asactionId, type, and data. data is the full order, identical to the Get Order response, including the deposit fields payment.payer.virtualAccountId, payment.reference, and payment.sender.
orders.payment.succeeded
orders.quote.created.
When an order event arrives, update the deposit in your app from the order. See 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-idheader. Process eachsvix-idonce. - 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
sequenceso older data never overwrites newer state. - Do not treat acceptance as final.
orders.payment.succeededmeans 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_sentcan 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
Track Deposits
The states and fields of each deposit
Test in Staging
Simulate deposits and receive every event

