# Deposit statuses

> Deposit statuses describe where a standalone top-up is in the payment flow, from creation to final settlement.

<table><thead><tr><th width="210">status</th><th width="226">description</th><th>allowed transitions</th></tr></thead><tbody><tr><td><code>created</code></td><td>A unique deposit address has been assigned to this deposit and the system is waiting for an on-chain payment.</td><td><code>processing</code>, <code>expired</code>, <code>cancelled</code></td></tr><tr><td><code>processing</code></td><td>An on-chain transaction was detected and is being checked. This may include confirmation checks, amount validation, and compliance screening.</td><td><code>completed</code>, <code>suspended</code></td></tr><tr><td><code>completed</code></td><td>Compliance screening passed and the merchant balance was credited.</td><td><em>Final status</em></td></tr><tr><td><code>suspended</code></td><td>Compliance screening did not pass; funds were not credited to the merchant balance.</td><td><em>Final status</em></td></tr><tr><td><code>expired</code></td><td>The payment link expired before a valid on-chain payment was detected. A payment that arrives at the deposit address within <strong>4 hours</strong> after expiry is still processed normally.</td><td><code>processing</code> (late payment within 4 hours after expiry); otherwise final</td></tr><tr><td><code>cancelled</code></td><td>The deposit was cancelled while still in <code>created</code> status. For an invoice-linked deposit cancelled because the customer switched to another currency on the payment page, a payment that still arrives at this deposit's address within <strong>4 hours</strong> is processed normally.</td><td><code>processing</code> (invoice-linked deposits cancelled by a currency switch, within 4 hours); otherwise final</td></tr><tr><td><code>failed</code></td><td>Reserved status in the public enum. Current deposit flows do not produce this status.</td><td><em>Final status</em></td></tr></tbody></table>

## Integration notes

Treat `completed` as the successful final status.

Treat `suspended` and `failed` as unsuccessful final statuses. Treat `expired` and `cancelled` as unsuccessful, but don't assume they are final until the late-payment window has passed (see below).

## Late payments

Every deposit gets its own address, so a payment that arrives after the deposit has closed can still be matched to it:

* If a payment reaches the address of an `expired` deposit within **4 hours** after expiry, the deposit moves `expired` → `processing` and continues through the normal flow (confirmations, AML screening, crediting) to `completed` or `suspended`. A `deposit.statusChanged` webhook is sent for each transition, as usual.
* The same applies to an invoice-linked deposit that was `cancelled` because the customer switched currency on the payment page and then still paid the address shown first. Invoice-linked deposits don't send `deposit.statusChanged` webhooks; follow `invoice.statusChanged` instead (see [Invoice statuses](https://docs.cryptonly.net/guides/invoices/statuses.md)).
* Payments that arrive after the 4-hour window, to deposits cancelled for any other reason, or in addition to a deposit that is already `completed` are not credited automatically. Contact **connect@cryptonly.net** with the deposit ID and transaction hash.

If your system closes orders on `expired`, make sure it can reopen them when a later `processing` / `completed` webhook arrives for the same deposit.

Cryptonly sends `deposit.statusChanged` on every deposit status transition for standalone deposits. Webhooks are **not** sent when a deposit is linked to an invoice (`invoiceId` is set) — use `invoice.statusChanged` for invoice payments instead.

## If a deposit is `suspended`

Unlike invoices, a standalone deposit that lands in `suspended` stays there — it's a final status, and no further `deposit.statusChanged` webhook will follow for that deposit. This means compliance review did not clear the transaction for automatic crediting. The funds are held on the deposit address and are not moved or credited. Contact **connect@cryptonly.net** with the deposit ID if you believe this needs manual follow-up.

Always use webhooks as the source of truth for status changes. `GET /deposit` and `GET /deposit/list` can be used as a fallback.

## Related pages

- [Processing lifecycle](https://docs.cryptonly.net/guides/deposits/processing-lifecycle.md): How a deposit moves through these statuses
- [Deposits](https://docs.cryptonly.net/guides/deposits.md): Creating a standalone top-up
- [Webhooks](https://docs.cryptonly.net/api-reference/webhooks.md): deposit.statusChanged is the source of truth
- [Invoice statuses](https://docs.cryptonly.net/guides/invoices/statuses.md): Invoice-linked deposits follow the invoice webhook