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, awaiting confirmation	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	None	Invoice invalidated or rejected	Cancel or flag for review

---

Additional status values

type	additionalStatus	What it means	Typical backend action
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 after only partial payment	Mark as underpaid/on-hold and contact customer

---

Minimal production rule set

If you want the shortest safe policy:

1. Ignore New.
2. Treat Processing as informational.
3. Fulfill only on Settled with normal status.
4. Review Overpaid, Underpaid, and PaidAfterExpiration manually.
5. Never use the browser redirect as your paid signal.

---

Recommended order-state mapping

Coinsnap event	Example local order state
New	pending_payment
Processing	processing or on_hold
Settled	paid
Expired	expired or cancelled
Invalid	cancelled

---

Related pages

• Custom Integration Path
• Quickstart
• Checkout Flow
• Webhook Handler Examples