Event types
Webhook events you can subscribe to.
| Event | When |
|---|---|
invoice.created | Invoice minted |
invoice.payment_detected | A payment was spotted. Optional progress event; do not fulfill. |
invoice.confirming | Confirmation is in progress. Optional; do not fulfill. |
invoice.paid | Invoice paid. Verify the actual amount before fulfilling. |
invoice.overpaid | Payment exceeds the amount due on paths that emit this event. |
invoice.partially_paid | Verified funds do not yet cover the required amount. |
invoice.manual_review | Payment requires review, for example after late arrival. Do not fulfill. |
invoice.expired | Payment window closed unpaid |
invoice.cancelled | Merchant cancelled |
The first payment notification can be invoice.paid. Earlier detected or confirming events are not required, and an overpayment on the current provider route also uses invoice.paid. Do not depend on a fixed event sequence.
Verify the signature, current invoice state, asset, order reference and received amount before fulfillment. Exact-payment invoices require the full final requested amount, including passed fees and quote rounding; manual review cannot waive a shortfall. If a positive tolerance is saved on the invoice, invoice.paid can instead mean the verified amount met that lower minimum. Gross and net still reflect only actual funds. See the fulfillment checks.
Handlers must be idempotent: the same event may be delivered more than once, and events can arrive out of order. Fulfill each order once and never move it backward because an older progress event arrived later.