Lesson 5 · Practitioner · Both · 13 min
Failures, Chargebacks Intro & Reconciliation
Treat declines, returns, chargebacks, and reconciliation as product features — not afterthoughts — with practical status design and ops workflows.
Objectives
- ▸Categorize soft declines vs hard declines vs post-settlement reversals
- ▸Explain chargebacks at an introductory level vs account returns
- ▸Design a reconciliation loop using UTRs/RRNs and settlement files
- ▸Know what to surface to customers vs what to keep in ops tooling
Not all failures are equal. Soft declines (insufficient funds, issuer unavailable, risk step-up) may be retried with another method or after customer action. Hard declines (invalid card, lost/stolen, do not honor) should stop retries. Timeouts create unknown states — the most dangerous UX bug is double capture from blind retries without idempotency keys.
- Use idempotency keys on auth/capture/refund APIs
- Map processor codes to user-safe messages; keep raw codes for ops
- Unknown/pending needs poll/webhook reconciliation, not assume fail
Idempotency is a payments feature
Network blips will double-submit. Your ledger and processor references must survive retries safely.
Key terms
Soft declineHard declineIdempotencyChargebackRepresentmentReturn codeRRNUTRSettlement file