Appendices
Appendix E — Failure Mode Catalogue
Payments fail in patterns. This catalogue lists the recurring ones by lifecycle stage: the symptom you see, the cause behind it, where to look first, and the chapter with the full story.
Authorization
| Symptom | Likely cause | Where to look | Chapter |
|---|---|---|---|
| Decline with generic "do not honor" | Issuer risk logic — catch-all refusal | Issuer decline code detail from PSP, retry on another day/method | Ch 9 |
| Soft decline spike | Insufficient funds, velocity limits, issuer outage | Decline-code mix by issuer/BIN | Ch 9, 15 |
| Hard declines recurring | Card closed, reported stolen, expired | Stop retrying; trigger credential refresh | Ch 15 |
| Cross-border declines elevated | Issuer distrust of foreign acquiring | Local acquiring / local MID strategy | Ch 8, 32 |
| 3DS abandonment | Challenge friction, broken redirect on mobile | Funnel between 3DS start and completion | Ch 11 |
Capture & Clearing
| Symptom | Likely cause | Where to look | Chapter |
|---|---|---|---|
| Auth approved, capture fails | Auth expired before capture | Days between auth and capture vs scheme limits | Ch 9 |
| Captured amount ≠ authorized amount | Tips, partial shipments, currency drift | Auth-capture mismatch rules for your MCC | Ch 9 |
| Duplicate charges | Webhook/system retries without idempotency keys | Idempotency handling in your integration | Ch 9, 32 |
| Partial capture unexpected | Split shipments, partial approval logic | Order-to-capture mapping | Ch 9 |
Settlement & Payouts
| Symptom | Likely cause | Where to look | Chapter |
|---|---|---|---|
| Payout smaller than sales | Fees netted from gross, refunds/chargebacks deducted | Settlement report line items | Ch 4 |
| Payout missing entirely | Rolling reserve, risk hold, verification lapse | PSP reserve terms and account status | Ch 26 |
| Settlement timing drift | Weekends, holidays, cutoff windows, T+2 conventions | Scheme calendar vs your accrual assumptions | Ch 4 |
Reconciliation
| Symptom | Likely cause | Where to look | Chapter |
|---|---|---|---|
| Books never match payouts | Matching at wrong granularity (batch vs transaction) | Ledger design; transaction-level references | Ch 4, 18 |
| FX differences | Conversion at different times/rates than booked | Settlement currency vs presentment currency | Ch 8 |
| Unidentified incoming transfers | Customers pay without references | Virtual accounts as reconciliation primitives | Ch 18 |
Recurring & Stored Credentials
| Symptom | Likely cause | Where to look | Chapter |
|---|---|---|---|
| MIT declines after months of success | Card reissued; stored PAN stale | Network tokens / account updater coverage | Ch 12, 16 |
| Renewal failures clustered at month end | Payday timing, expired cards batch | Retry schedule vs calendar | Ch 15 |
| "Unauthorized" recurring disputes | Weak mandate evidence, unclear descriptor | CIT/MIT flags, mandate records, billing descriptor | Ch 16 |
| Direct debit returns weeks later | Revocation, closed accounts, disputes inside refund window | Scheme return codes and windows | Ch 20 |
Disputes
| Symptom | Likely cause | Where to look | Chapter |
|---|---|---|---|
| Chargeback rate creeping up | Friendly fraud, unclear descriptors, delivery disputes | Reason-code distribution | Ch 13 |
| Losing winnable representments | Evidence not matched to reason code | Representment package quality | Ch 13 |
| Network monitoring program letter | Dispute ratio breached scheme thresholds | Chargeback ratio trend; remediation plan | Ch 13, 26 |
Compliance & Off-boarding
| Symptom | Likely cause | Where to look | Chapter |
|---|---|---|---|
| Sudden account termination by PSP | Risk-appetite change, prohibited-category drift, MATCH listing | Your MCC, dispute ratio, content of recent flags | Ch 26 |
| Funds frozen pending "review" | AML alert, sanctions near-match, unusual velocity | KYC file freshness; transaction pattern changes | Ch 26 |
| Stablecoin funds stuck | Off-ramp banking issues, blacklisted address upstream | Issuer/ramp status; address screening | Ch 28, 30 |
| QR/proxy payment to wrong recipient | Stale proxy mapping, static QR misuse | Proxy registry, dynamic QR adoption | Ch 19 |
Using this catalogue — Most payment incidents are one of these patterns wearing a costume. Identify the lifecycle stage first, then the symptom row; the chapter reference gives you the mechanism, which is what you actually debug against.