Design a Payment Dispute & Chargeback System

Hard45 min
1 / 30
understanding•11 min read

Problem Statement: The Chargeback Lifecycle and Financial Risk

Frames the dispute system as a multi-party financial workflow with strict network deadlines, not a simple ticketing system.

Problem statement

Design a Payment Dispute & Chargeback System that manages the full lifecycle of payment disputes initiated by cardholders, issuing banks, or card networks. The platform must ingest dispute notifications from processors and networks, gather evidence (order details, shipping proofs, customer communication logs, AVS/CVV verification records), submit representment cases within strict network deadlines, track status through pre-arbitration and arbitration, and log final settlement outcomes.

This is not a customer-support ticketing system. A chargeback is a financial instrument reversal governed by card network rules (Visa, Mastercard, Amex, Discover) with hard deadlines measured in calendar days. Missing a representment deadline by one hour means automatic loss of the disputed amount plus a $15–$50 fee. The system must therefore treat time as a first-class constraint and network messages as the source of truth.

Why the problem is distinctive

A refund system reverses a payment by merchant choice. A chargeback system reverses a payment against merchant will, initiated by the cardholder's bank, and the merchant must prove the transaction was legitimate. The asymmetry changes everything:

  • Evidence burden: The merchant must produce compelling evidence within 20–45 days depending on the reason code and network.
  • Network protocol: Visa uses Visa Resolve Online (VROL) with specific message formats; Mastercard uses its Dispute Resolution framework; Amex has its own Dispute Services portal. Each has different reason codes, deadlines, and submission formats.
  • Financial finality: Once arbitration rules, the outcome is binding. The system must record the final state immutably for accounting reconciliation.
  • Regulatory overlay: PCI DSS governs card data handling. PSD2 in Europe and Regulation E in the US impose consumer protection timelines.

The four architectural planes

  1. Ingestion plane: Receives dispute notifications from processors (Stripe, Adyen, Braintree) and card networks via webhooks, batch files (IPM for Mastercard), and API polling.
  2. Case management plane: Owns the dispute lifecycle state machine, evidence collection, deadline tracking, and analyst assignment.
  3. Network integration plane: Translates internal case state into network-specific message formats, submits representment evidence, and parses network responses.
  4. Settlement and analytics plane: Records final outcomes, reconciles with payment ledgers, computes win rates by reason code and merchant segment, and feeds fraud models.

Public operating baseline versus design assumptions

Visa reported processing over 65,000 transactions per second at peak in 2023. Global chargeback rates average 0.5–1.5% of e-commerce transaction volume according to the Nilson Report. Stripe's public documentation describes its Disputes API processing evidence submission for millions of disputes annually. Mastercard acquired Ethoca in 2019 specifically to enable pre-dispute resolution through its Rapid Dispute Resolution (RDR) network.

For capacity planning, this answer explicitly assumes a mid-size payment platform processing 50 million transactions per month, a 1.2% dispute rate yielding 600,000 disputes annually (~1,650/day average, 8,250/day at 5× seasonal peak), with 40% of disputes receiving automated evidence submission and 60% requiring analyst review.

Success criteria

Correctness: Zero missed representment deadlines. Every dispute that enters the system receives either a submitted response or a documented acceptance-of-liability before its network deadline.

Latency: Dispute ingestion to case creation under 5 seconds p99. Evidence retrieval for analyst review under 2 seconds p95. Network submission confirmation under 30 seconds p99.

Auditability: Every state transition, evidence upload, network message, and analyst action is recorded in an immutable, append-only audit trail with actor identity, timestamp, and reason code.

Security: No full PAN stored anywhere in the dispute system. All evidence documents encrypted at rest (AES-256) and in transit (TLS 1.3). Access governed by role-based controls with quarterly access reviews.

Scalability: Handle 10× the assumed dispute volume without architectural change. Support 3 new card networks without rewriting the integration layer.

Key Highlights

  • •A chargeback is a financial reversal governed by network rules, not a support ticket.
  • •Missing a representment deadline by one hour means automatic loss plus fees.
  • •The system has four planes: ingestion, case management, network integration, settlement.
  • •Assumed scale: 50M transactions/month, 1.2% dispute rate, 600K disputes/year.
  • •Zero missed deadlines is the primary correctness invariant.
Lead With the Deadline Constraint
State in the first two minutes that the system's primary invariant is zero missed representment deadlines. This immediately distinguishes a payments architecture from a generic case-management system.
Do Not Design a Ticketing System
A dispute is not a support ticket. It has hard network deadlines, financial finality, regulatory requirements, and multi-party settlement. Designing it as Zendesk-with-database will fail a serious interview.

Section Rescue Kit

Buzzwords to use:

RepresentmentReason Code

Safe statements:

  • "I will separate dispute ingestion from case management because network messages and internal workflow have different consistency needs."
  • "Before selecting databases, let me define which decisions are deadline-bound, which are evidence-bound, and which are settlement-bound."
Design a Payment Dispute & Chargeback System - System Design | WinJob | WinJob