> ## 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.

# Track Deposits

> Follow each bank transfer into a virtual account as an order, from arrival to delivery or return

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](https://docs.crossmint.com/virtual-accounts/guides/open-a-virtual-account.md).
* **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](https://docs.crossmint.com/payments/advanced/webhooks.md).

## Read a Deposit

Read a deposit with [Get Order](https://docs.crossmint.com/onramp/api-reference/get-order.md). A deposit order has three fields of its own inside `payment`:

```json Deposit order (excerpt) theme={null}
{
    "orderId": "b2959ca5-65e4-466a-bd26-1bd05cb4f837",
    "phase": "delivery",
    "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"
        }
    }
}
```

| Field | Description |
| :- | :- |
| `payment.payer.virtualAccountId` | The account the transfer arrived in |
| `payment.reference` | The reference received with the transfer, as the sender wrote it, or `null` when there is none |
| `payment.sender.name` | The sender's name as the bank supplied it. It is not the user's verified name |
| `payment.sender.institutionName` | The sender's bank, or `null` |
| `payment.sender.accountLast4` | The last four characters of the sender's IBAN or account number, or `null` |
| `payment.sender.rail` | The rail of the transfer: `sct` for SEPA, `sct-inst` for SEPA Instant |
| `payment.sender.classification` | `first-party` when the sender's name matches the user's verified name, `third-party` when it does not, `inconclusive` when the name is empty or unreadable |

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

```bash cURL theme={null}
curl --request GET \
    --url https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/orders \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/orders", {
    method: "GET",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
    },
});

console.log(await response.json());
```

```python Python theme={null}
import requests

response = requests.get(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/orders",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
)

print(response.json())
```

```json Response (orders abbreviated) theme={null}
{
    "data": [
        {
            "orderId": "b2959ca5-65e4-466a-bd26-1bd05cb4f837",
            "phase": "completed",
            "payment": {
                "status": "completed",
                "reference": "Invoice 123",
                "payer": {
                    "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35"
                }
            }
        }
    ],
    "nextCursor": "example-cursor"
}
```

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](https://mintcdn.com/crossmint/2jd6Af-5zuDMpBOn/images/virtual-accounts/track-deposits/deposit-states.png?fit=max\&auto=format\&n=2jd6Af-5zuDMpBOn\&q=85\&s=9e8ec1070c4c40484309d9d44aa3d727)

| Deposit | `phase` and `payment.status` | Other fields |
| :- | :- | :- |
| In review | `payment` `in-review` | No reason and no date |
| Converting | `delivery` `completed` | None |
| Delivered | `completed` `completed` | `lineItems[].delivery.txId` and `tokens` |
| Sending back | `payment` `failed` | `failureReason` `returnStatus` `pending` |
| Return failed | `payment` `failed` | `failureReason` `returnStatus` `failed` |
| Sent back | `completed` `failed` | `failureReason` `returnStatus` `sent` `payment.refunded` |

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`:

```json Returned deposit (excerpt) theme={null}
{
    "orderId": "5d0c8f1e-7b2a-4c39-9a51-0e6b2f4d8a17",
    "phase": "completed",
    "payment": {
        "status": "failed",
        "method": "bank-transfer",
        "currency": "eur",
        "failureReason": {
            "code": "third-party-sender",
            "message": "The sender name does not match the account holder. The money returns to the sender.",
            "railCode": null
        },
        "returnStatus": "sent",
        "refunded": {
            "amount": "900.00",
            "currency": "eur",
            "sentAt": "2026-11-20T10:04:12.000Z",
            "railReference": "9c4e7a12-5b3d-4f8e-a1c6-2d7b0e5f3a84"
        },
        "received": {
            "amount": "900.00",
            "currency": "eur"
        },
        "payer": {
            "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35"
        },
        "reference": null,
        "sender": {
            "name": "JOHN SMITH",
            "institutionName": "ING",
            "accountLast4": "0917",
            "rail": "sct",
            "classification": "third-party"
        }
    }
}
```

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](https://docs.crossmint.com/virtual-accounts/guides/handle-webhooks.md) 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.code` | When |
| :- | :- |
| `unsupported-rail` | The transfer is not SEPA or SEPA Instant in EUR, such as a SWIFT transfer |
| `virtual-account-not-active` | The account is `pending`, `suspended`, `failed`, or `closed` |
| `verification-required` | The user must verify their identity again, then send the transfer again |
| `third-party-sender` | The sender is not the user, or the sender's name is empty or unreadable |
| `below-minimum` | The amount is below the minimum per deposit, or does not cover the fees |
| `above-maximum` | The amount is above the maximum per deposit |
| `conversion-failed` | The deposit could not be converted |
| `delivery-failed` | The stablecoins could not be delivered to the wallet |
| `hold-expired` | A review could not finish in time |
| `deposit-not-accepted` | The transfer cannot be accepted. The order gives no further reason |

`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.

```json Delivered deposit (excerpt) theme={null}
{
    "orderId": "c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
    "phase": "completed",
    "lineItems": [
        {
            "chain": "solana",
            "quote": {
                "status": "valid",
                "charges": {
                    "transferFee": {
                        "amount": "0.10",
                        "currency": "eur"
                    },
                    "crossmintFees": {
                        "amount": "0.00",
                        "currency": "eur"
                    },
                    "fees": {
                        "type": "exact",
                        "amount": "0.10",
                        "currency": "eur"
                    }
                },
                "totalPrice": {
                    "amount": "200.00",
                    "currency": "eur"
                }
            },
            "delivery": {
                "status": "completed",
                "recipient": {
                    "locator": "solana:7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
                    "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px"
                },
                "txId": "3Ry7nQ5wK2mT8vB4hZ6dF1sJ9gL2aE7uC5nX3yP8qW4rD6mV1bH9jS2fN5kG8zA3cT7xM4wQ1eR6tY9uE2pLk",
                "tokens": [
                    {
                        "locator": "solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                        "quantity": "230724580",
                        "symbol": "USDC",
                        "decimals": 6
                    }
                ]
            }
        }
    ],
    "quote": {
        "status": "valid",
        "totalPrice": {
            "amount": "200.00",
            "currency": "eur"
        },
        "exchangeRate": {
            "sourceCurrency": "eur",
            "destinationCurrency": "usdc",
            "rate": "1.1542"
        }
    }
}
```

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

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

> [card] [Get Order API](https://docs.crossmint.com/onramp/api-reference/get-order.md)
>
> Every field of an order
