Webhook Status Reference
Use this page as the compact decision table for webhook handling.
If you need payload examples or signature-verification code, see Webhooks Overview.
Main statuses
type | additionalStatus | What it means | Typical backend action |
|---|---|---|---|
New | None | Invoice created | Usually no action |
Processing | None | Payment detected. Always precedes Settled, including for Lightning | Mark order as processing/on-hold, do not fulfill yet |
Settled | None | Payment confirmed | Mark as paid and fulfill |
Expired | None | Invoice expired without payment | Mark as expired/cancelled if your business flow requires it |
Invalid is an invoice status, not a webhook event. No Invalid webhook is sent. Read it from GET /api/v1/stores/{storeId}/invoices/{invoiceId} if you need it, and use Expired as the terminal webhook signal.
Additional status values
type | additionalStatus | What it means | Typical backend action |
|---|---|---|---|
Settled | None | Paid in full, or short by less than the store's underpayment tolerance | Mark as paid and fulfill |
Settled | Overpaid | Customer paid more than the invoice amount | Mark as paid, then review refund or credit policy |
Settled | PaidAfterExpiration | Payment arrived after the invoice had already expired | Mark for manual review before fulfillment |
Expired | Underpaid | Invoice expired short by more than the tolerance | Mark as underpaid/on-hold and contact customer |
Values the platform does not produce
Older Coinsnap PHP and WordPress libraries define these constants. Nothing in the platform emits them, and no webhook or invoice will ever carry one. Do not branch on them.
| Legacy constant | Use instead |
|---|---|
PaidPartial | Underpaid |
PaidOver | Overpaid |
PaidLate | PaidAfterExpiration |
Marked | nothing, there is no equivalent |
Minimal production rule set
If you want the shortest safe policy:
- Ignore
New. - Treat
Processingas informational. - Fulfill only on
SettledwithadditionalStatus: None. - Review
Overpaid,Underpaid, andPaidAfterExpirationmanually. - Never use the browser redirect as your paid signal.
Step 3 fulfills a payment short by less than your store's underpayment tolerance, because such a payment settles as Settled plus None. Compare amount against totalPaid on the invoice if you need the shortfall.
Recommended order-state mapping
| Coinsnap event | Example local order state |
|---|---|
New | pending_payment |
Processing | processing or on_hold |
Settled | paid |
Expired | expired or cancelled |