Stripe Retry Safety Verdict

Decides whether a payment call site or webhook handler can do its work TWICE. Pure function over facts visible at the call site: no I/O, no Stripe dependency.

THE MEASUREMENT: real Stripe test-mode API calls and real SDK signature construction. Nothing inferred from documentation.

WITHOUT A KEY, A RETRY CHARGES TWICE. Two identical PaymentIntent creations with no idempotency key returned pi_3U1asZPgyWISXbB71TUdrwUy and pi_3U1asZPgyWISXbB70HItTbOX -- two separate intents. A timeout the client retried, a proxy that replayed, a double-click. From Stripe's side two distinct requests arrived and both were honoured, so nothing reports a duplicate.

WITH A KEY, STRIPE IS LOUD -- NOT SILENT. Same key and same parameters returned the SAME PaymentIntent. Same key with a DIFFERENT amount was REJECTED with a typed StripeIdempotencyError. THIS IS THE OPPOSITE OF WHAT WAS EXPECTED: the assumption going in was that Stripe would silently return the original $10 intent while the caller believed they had charged $50. It does not. So this package treats a MISSING or UNSTABLE key as the finding, and does not second-guess Stripe where a key is used correctly.

SIGNATURE VERIFICATION DOES NOT DEDUPLICATE. Stripe retries a webhook until it gets a 200, so the same event arrives more than once:

    delivery #1: constructEvent   ACCEPTED -- event evt_probe_00000001
    delivery #2: constructEvent   ACCEPTED -- event evt_probe_00000001
    delivery #3: constructEvent   ACCEPTED -- event evt_probe_00000001

Three out of three. The signature proves the event is genuinely Stripe's; it says NOTHING about whether you have already acted on it. A handler that fulfils an order in the success branch fulfils it once per delivery. The event id IS stable across redeliveries -- that is your dedup key, and nothing records it for you.

THE TOLERANCE WINDOW BOUNDS AN ATTACKER, NOT STRIPE. A one-hour-old signature was REJECTED as outside the tolerance zone, so the default 300 seconds catches a captured request replayed later. It does nothing about Stripe's own redelivery, which arrives FRESHLY SIGNED and inside the window every time. Two different problems; only one has a built-in defence.

IT ALSO CATCHES the key that is regenerated per ATTEMPT -- a fresh uuid inside the retry loop is not an idempotency key, and the call looks protected in review because the parameter is present. It is the STABILITY of the value that does the work, and that is invisible at the call site.

IT REFUSES rather than guesses on unknown retryability -- saying plainly that for a payment call the answer is almost always yes -- and asks about signature verification and event-id deduplication SEPARATELY, because they are different protections and neither substitutes for the other.

VERIFIED: 18 tests, every one of 8 mutations observed FAILING before restore.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluatePaymentSite(site: CallSite): Verdict;

  export type CallSite = ChargeSite | WebhookSite;
  export type Verdict = | { status: "SAFE";