Skip to main content
Every bank transfer into a virtual account becomes one order, as soon as the banking partner reports it, including the transfers that go back to the sender. You follow a deposit with the same order webhooks and the same Orders API as any onramp order. A deposit ends delivered or returned, never both.

Prerequisites

  • Account: an active virtual account, opened as in Open a Virtual Account.
  • API Key: a server API key with the orders.read scope. In staging, all scopes are included by default.
  • Webhook endpoint: an endpoint subscribed to the order events, set up as in Webhooks.

Read a Deposit

Read a deposit with Get Order. A deposit order has three fields of its own inside payment:
Deposit order (excerpt)
Use payment.reference to match deposits to invoices in your system. Do not assume it is unique: two transfers can carry the same reference, and each is its own order.

List the Deposits of an Account

Response (orders abbreviated)
Each item is the full order, as Get Order returns it, newest first. An account with no deposits returns an empty data, and the history stays readable after the account closes. To list deposits across accounts, add virtualAccountId to the project-wide list at GET /api/2025-06-15/orders, with up to 20 comma-separated account IDs.

Deposit States

Read phase, payment.status, and payment.returnStatus together to know where a deposit is.
Deposit states: a bank transfer arrives and is converting after orders.payment.succeeded, in review after orders.payment.in_review, or sending back after orders.payment.failed. A deposit in review moves to converting or to sending back, and a converting deposit can go into review or be sent back. A converting deposit is delivered with orders.delivery.completed, which is final. A deposit that is sending back is sent back with orders.payment.refund_sent, or its return fails with orders.payment.refund_failed and Crossmint makes a new attempt
A deposit in review waits on a check. No action from you or the user ends a review, and the API gives no reason and no date for it. A deposit that goes back returns in full to the sending account, with nothing deducted. sent means the return left for the sender’s bank, not that the bank credited it. payment.refunded appears together with sent:
Returned deposit (excerpt)
Treat payment.status, payment.returnStatus, and failureReason.code as extensible.

Events

Each step of a deposit sends an order webhook that carries the full order as data. A delivered deposit sends orders.quote.created, orders.payment.succeeded, orders.delivery.initiated, and orders.delivery.completed, in that order. See Virtual Account Webhooks for every event, its payload, and the order of events for each outcome.

Why a Deposit Goes Back

payment.failureReason.code says why, and payment.failureReason.message is the text to show the user. failureReason.railCode holds the code of the rail when the bank or the rail sent the transfer back, and is null otherwise.

Read the Delivered Amount

The wallet receives the amount received minus the fees on the order, times quote.exchangeRate.rate, in the token of the account. The rate is fixed when the deposit converts. For a USDC account it already includes the markup, so the fees on the order do not list it.
Delivered deposit (excerpt)
This example is a deposit into an account that delivers USDC on Solana. EUR 200.00 minus EUR 0.10 of fees, times 1.1542, is 230.724580 USDC. The rate and fees are illustrative.

Next Steps

Test in Staging

Simulate deposits and force each outcome

Get Order API

Every field of an order