stripe-refund-dispute-lifecycle

name

stripe-refund-dispute-lifecycle

description

Complete Stripe refund and dispute lifecycle handling. PROACTIVELY activate for: (1) charge.refunded handler design, (2) charge.dispute.created / charge.dispute.closed handlers, (3) Refund delta computation from event.data.previous_attributes.amount_refunded, (4) Dispute-hold past_due status management, (5) shouldRestoreStatus predicate with satisfies Record<Stripe.Dispute.Status, boolean>, (6) Credit-pack vs subscription refund differentiation, (7) Checkout Session lookup for refund proportion math, (8) Allowlist default-deny for external enums, (9) stripe.checkout.sessions.list({payment_intent}) pattern, (10) Dispute outcome branch logic (won / lost / warning_closed / prevented). Provides: full handler patterns for all three events, predicate examples, credit-pack vs subscription math, exhaustive switch patterns.

Quick Reference

Event	Action	Key rule
charge.refunded	Revoke credits proportional to refund delta	G2 — previous_attributes.amount_refunded
charge.dispute.created	Set user past_due + store checkpoint	G1 + G9
charge.dispute.closed	won / warning_closed / prevented -> restore; lost -> no-op (charge.refunded handles); else -> no-op	G5 + G7

Refund source priority	When to use
event.data.previous_attributes.amount_refunded (G2)	Primary — always prefer
charge.refunds.data (sorted by created desc)