Deposit statuses
| status | description | allowed transitions |
|---|---|---|
created | A unique deposit address has been assigned to this deposit and the system is waiting for an on-chain payment. | processing, expired, cancelled |
processing | An on-chain transaction was detected and is being checked. This may include confirmation checks, amount validation, and compliance screening. | completed, suspended |
completed | Compliance screening passed and the merchant balance was credited. | Final status |
suspended | Compliance screening did not pass; funds were not credited to the merchant balance. | Final status |
expired | The payment link expired before a valid on-chain payment was detected. A payment that arrives at the deposit address within 4 hours after expiry is still processed normally. | processing (late payment within 4 hours after expiry); otherwise final |
cancelled | The deposit was cancelled while still in created 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 4 hours is processed normally. | processing (invoice-linked deposits cancelled by a currency switch, within 4 hours); otherwise final |
failed | Reserved status in the public enum. Current deposit flows do not produce this status. | Final status |
Integration notes
Section titled “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
Section titled “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
expireddeposit within 4 hours after expiry, the deposit movesexpired→processingand continues through the normal flow (confirmations, AML screening, crediting) tocompletedorsuspended. Adeposit.statusChangedwebhook is sent for each transition, as usual. - The same applies to an invoice-linked deposit that was
cancelledbecause the customer switched currency on the payment page and then still paid the address shown first. Invoice-linked deposits don’t senddeposit.statusChangedwebhooks; followinvoice.statusChangedinstead (see Invoice statuses). - Payments that arrive after the 4-hour window, to deposits cancelled for any other reason, or in addition to a deposit that is already
completedare not credited automatically. Contact [email protected] 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
Section titled “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 [email protected] 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.