Crypto payment statuses
Use this page when your checkout, webhook worker, support desk, or finance workflow needs to decide what to do after an invoice changes state. Webhooks are notifications; reload the invoice status before fulfillment-sensitive actions.
Status table
| Status | Public name | Merchant action | Primary doc |
|---|---|---|---|
awaiting_deposit | Awaiting payment | wait · Wait | /docs/invoices |
seen | Payment seen | wait · Wait | /docs/invoices |
confirming | Confirming | wait · Wait | /docs/invoices |
confirmed | Confirmed | wait · Wait | /docs/invoices |
paid | Paid | safe_to_fulfill · Safe to fulfill | /docs/invoices |
expired | Expired | closed · Closed | /docs/invoices |
cancelled | Cancelled | closed · Closed | /docs/invoices |
underpaid | Underpaid | support_review · Support review | /docs/refunds |
overpaid | Overpaid | support_review · Support review | /docs/refunds |
late | Late payment | support_review · Support review | /docs/refunds |
review | Review required | support_review · Support review | /docs/refunds |
refunded | Refunded | closed · Closed | /docs/refunds |
Fulfillment rule
Treat paid as the normal fulfillment state. Treat awaiting_deposit, seen, confirming, and confirmed as wait states. Treat underpaid, overpaid, late, and review as support review states before shipping
goods or crediting access.
Webhook and polling flow
- Receive the webhook and verify its raw-body signature.
- Dedupe by event ID and invoice ID before side effects.
- Reload the invoice from the API before fulfillment-sensitive action.
- Store the status transition and the last checked timestamp.
- Use polling as a fallback when webhook delivery is delayed.
Related docs: invoices, webhooks, webhook verification, refunds, and idempotency.