Payment specs need failure matrix

Short summary

Payment specs often fail because they dismiss failure modes with 'retry on error.' This article proposes categorizing failures into five types—network timeout, soft decline, hard decline, fraud review, 3DS—then anchoring all downstream decisions to this taxonomy. Key insight: retry policy depends on failure category and decline code, not HTTP status; idempotency keys survive retransmission within a logical attempt; webhooks are the ledger, not sync responses.

• •Collapse failure modes into a five-category taxonomy (network timeout, soft/hard decline, fraud review, 3DS) before designing retry logic
• •Retry policy is a function of failure category and decline code, not HTTP status—Stripe 402 could be soft (customer action) or hard (never retry)
• •Idempotency keys must survive retransmission within a logical attempt; new attempts get new keys; webhooks, not sync responses, are the source of truth

Generated with AI, which can make mistakes.