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.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 |
No webhook fires when the payment row is first created — the synchronous POST /payments response covers that state. 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). 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.pending | A subscription charge was accepted by the PSP, awaiting capture or 3DS |
subscription.succeeded | First charge or a renewal charge succeeded |
subscription.failed | A subscription charge attempt failed (first charge, renewal, or retry) |
subscription.cancelled | The subscription terminated — merchant cancel via DELETE /subscriptions/{id}, retries exhausted, or a non-recoverable decline (terminal) |
Treat subscription.succeeded after the first one as "renewal — extend the customer's access by another billingIntervalDays." The event string is the same for the first charge and every renewal, but each cycle is a distinct event with its own eventId — dedupe on eventId and count each subscription.succeeded as one cycle. data.currentPeriodStart / data.currentPeriodEnd tell you which period that charge paid for.
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 or refunded, 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.