Event types
Every webhook MintCash emits, when it fires, and whether it's terminal.
Every webhook's event field follows the pattern <entity>.<status>. The type field tells you what's inside data. The event field tells you which state transition fired.
Payment events (type: "payment")
| Event | When it fires | Terminal |
|---|---|---|
payment.created | Payment row created, waiting on the PSP or customer redirect | No |
payment.pending | PSP accepted the charge, awaiting capture or 3DS completion | No |
payment.authorized | Funds authorized but not yet captured | No |
payment.succeeded | Charge captured — fulfil the order on this event | No¹ |
payment.failed | Charge declined or PSP returned an error | Yes |
payment.partially_refunded | A partial refund succeeded; further refunds are still possible | No |
payment.voided | Authorization voided before capture | Yes |
Refund transitions (payment.partially_refunded, payment.refunded, payment.refund_failed) keep the payment. event prefix but are delivered with type: "refund" — see Refund events below.
¹ succeeded is not strictly terminal because the payment can still be refunded (delivered as a type: "refund" event) or voided. Once you receive a terminal event for a paymentId, no further events fire for it.
Subscription events (type: "subscription")
Subscription events mirror payment events for the underlying invoice charges, plus the lifecycle transitions of the subscription itself.
| Event | When it fires |
|---|---|
subscription.succeeded | First charge or a renewal charge succeeded |
subscription.failed | First charge or a renewal charge failed |
subscription.cancelled | Cancelled by merchant, or all retries exhausted (terminal) |
Treat subscription.succeeded after the first one as "renewal — extend the customer's access by another billingIntervalDays."
Refund events (type: "refund")
| Event | When it fires |
|---|---|
payment.partially_refunded | A partial refund succeeded; further refunds still possible |
payment.refunded | The payment is now fully refunded |
payment.refund_failed | A refund attempt couldn't be processed |
What "terminal" means in practice
When a payment hits failed, refunded, or voided, no further events will fire for that paymentId. Same for a subscription that hits failed or cancelled.
Use this to safely clean up state: archive the order record, close the dunning ticket, mark the customer record. You won't get any more updates about that resource.