Payment Provider Router

Concept of the skill

What it is: The typed dispatch layer that sends verified payment events to the correct business handler. Mental model: Verification proves the event is authentic; the router decides what business operation the event represents. Why it exists: Payment events are high-impact and retried by providers, so ambiguous routing can duplicate work or miss fulfillment. What it is NOT: It is not webhook signature verification, subscription database writes, or provider SDK setup. Adjacent concepts: Event type maps, handler isolation, provider abstraction, idempotency. One-line analogy: It is the switchboard that sends a verified payment event to the right desk. Common misconception: Unknown events should return an HTTP error; for Stripe, acknowledging and logging unknown-but-valid events prevents retry storms.

Coverage

• The routing table — a typed dispatch map from Stripe.Event["type"] to handler functions, with a structured "unknown event" fallback that returns 200 (to prevent Stripe retry storms) and logs the unhandled type
• Handler isolation — each handler receives only the specific event subtype it needs (e.g. Stripe.CheckoutSessionCompletedEvent), not the generic Stripe.Event, to avoid casts inside handlers
• Provider abstraction — how to wrap the Stripe-specific router behind a PaymentEvent canonical type so a future provider can be added without changing handler code
• Error surface — handlers must catch their own errors and return a structured result; an uncaught exception must not produce a 500 that triggers Stripe's retry mechanism with an exponential backoff cascade
• Event type coverage audit — which event types are handled, which are known-ignored (acknowledged with a comment), and which are genuinely unknown