Low Level Design: Payment Dispute Resolution Service

A payment dispute resolution service manages the lifecycle from the moment a customer contests a charge through investigation, bank communication, merchant response, and final financial settlement. It must enforce tight deadlines (card networks impose chargeback response windows measured in days), maintain a complete audit trail, and interface with banks and card networks over ISO 8583 messaging or modern REST APIs.

Dispute Schema

disputes(
  id,
  transaction_id,
  user_id,
  merchant_id,
  reason_code,
  status,
  amount,
  currency,
  opened_at,
  response_deadline,
  resolved_at,
  resolution
)

The reason_code maps to card-network reason categories: fraud, not as described, not received, duplicate charge, subscription canceled. Each reason code carries different evidence requirements and deadline rules. The response_deadline is computed from opened_at based on the card network rules (Visa and Mastercard publish detailed chargeback guides with per-reason-code deadlines).

Chargeback Lifecycle State Machine

A dispute moves through a fixed state machine:

opened: dispute created, evidence collection begins, merchant notified
evidence_submitted: merchant has uploaded their response package
under_review: evidence sent to the bank or card network for adjudication
won: dispute resolved in the merchant favor, funds retained
lost: dispute resolved in the customer favor, funds returned
pre_arbitration: merchant or issuer escalates after initial resolution (optional, network-specific)

State transitions are timestamped and actor-attributed. Illegal transitions (e.g., won → evidence_submitted) are rejected.

Evidence Collection API

The merchant-facing API accepts a structured evidence package. Evidence types vary by reason code:

Proof of delivery: tracking number, carrier confirmation, delivery signature
Customer communication logs: email threads, chat transcripts showing the customer acknowledged receipt
Receipts and invoices: order confirmation, itemized receipt
Refund records: proof that a refund was already issued
Terms of service: for subscription disputes, the signed terms and cancellation policy

Files are stored in object storage (S3-compatible). Metadata and file references are stored in an evidence table linked to the dispute. The API validates file types, enforces size limits, and checks that the submission arrives before the response_deadline.

Merchant Response Window Enforcement

A scheduled job runs frequently (every few minutes) to check disputes where response_deadline is approaching or past. Merchants receive notifications at defined intervals before the deadline (e.g., 7 days out, 3 days out, 24 hours out). If the deadline passes without a submission, the dispute is automatically marked as lost and financial settlement proceeds. This prevents the service from holding funds indefinitely when merchants are unresponsive.

Bank and Card Network Communication

Communication with issuing banks and card networks happens over two main channels:

ISO 8583 messaging: the traditional financial messaging format, used for chargeback notifications and responses in many legacy integrations. Messages are exchanged over TCP with a message queue for reliability.
Card network APIs: Visa Dispute Management System (VDMS) and Mastercard Connect offer REST APIs for newer integrations. The service wraps both behind an adapter interface.

Outbound messages include the dispute response package. Inbound messages deliver chargeback notifications, retrieval requests, and final adjudication outcomes. All messages are logged before processing (at-least-once delivery with idempotency keys).

Automated Pre-Screening

Not every dispute needs manual review. Pre-screening rules auto-resolve clear-cut cases before analyst time is spent:

Duplicate dispute: same transaction already has a resolved dispute → reject the new one
Already refunded: the transaction was refunded before the dispute arrived → auto-close, notify bank
Outside dispute window: transaction is older than the card-network dispute window → reject
Amount mismatch: claimed amount exceeds original transaction amount → flag for review

Resolution and Financial Settlement

When adjudication completes (by the bank, the card network, or a pre-screening rule), the resolution engine executes the financial outcome:

Dispute won: funds already held are released back to the merchant. Chargeback fee is waived if the network allows it.
Dispute lost: the disputed amount is debited from the merchant account and credited back to the cardholder. Chargeback fee is applied.

Settlement entries are written to the ledger service as double-entry bookkeeping records. The dispute record is updated with resolution and resolved_at. Both the merchant and the customer receive a notification.

Audit Log and SLA Tracking

Every state transition, evidence upload, outbound message, inbound notification, and settlement entry is written to an append-only audit log. SLA metrics are computed from the log: time to first merchant notification, time to evidence submission, time to resolution. Breached SLAs surface in an ops dashboard and trigger alerts. The audit log is the source of truth for any regulatory inquiry or dispute about the dispute process itself.

Interview Tips

Interviewers want to see that you understand the deadline-driven nature of chargebacks and have a concrete plan for enforcing them. Cover the ISO 8583 / card network API layer — it signals domain knowledge. Be ready to discuss idempotency in the settlement step: double-crediting a customer or double-debiting a merchant is a serious production incident. Mention that the ledger write and the dispute status update must be atomic or at least idempotent with compensation logic.

Frequently Asked Questions

What is a payment dispute resolution service?

A dispute resolution service manages the end-to-end lifecycle of a payment dispute — from the moment a customer claims a transaction is unauthorized or a product was not received, through evidence collection and submission, to a final win/loss decision by the card network or arbitration panel. It coordinates between merchants, cardholders, acquiring banks, and card networks (Visa, Mastercard) while enforcing strict regulatory deadlines at each stage. The system must track state precisely, because missing a single deadline automatically results in a loss for the merchant.

What is the chargeback lifecycle in system design?

The lifecycle flows through well-defined stages: (1) dispute opened — the cardholder files a claim with their issuing bank; (2) retrieval request — the acquirer requests transaction documentation from the merchant; (3) chargeback issued — funds are provisionally returned to the cardholder and debited from the merchant; (4) representment — the merchant submits evidence to contest the chargeback; (5) second chargeback — if the issuer rejects the representment, a second chargeback is issued; (6) arbitration — either party escalates to the card network for a binding ruling. Each stage has a strict calendar-day deadline (typically 7–45 days depending on stage and network) that the system must track and act on automatically.

How do you collect and manage evidence for a dispute?

Evidence collection is triggered the moment a dispute is opened. The service calls internal APIs to gather transaction logs, delivery confirmations, customer communication records, IP and device fingerprints, and signed terms-of-service acceptance. For physical goods, it pulls carrier tracking data. Evidence is stored as structured records linked to the dispute ID in an object store (S3), with metadata indexed in a relational database for fast retrieval. A merchant-facing portal allows manual upload of supplementary documents. Before submission, an evidence-assembly job packages all artifacts into a PDF or structured data bundle in the format required by the card network’s dispute portal or API (e.g., Visa Resolve Online, Mastercard Connect).

How do you enforce response deadlines in a dispute service?

Deadlines are modeled as first-class entities: when a dispute advances to a new stage, the service calculates the due date based on the card network’s rules and writes a deadline record to a deadlines table. A scheduler (e.g., a cron job or a delayed-job queue like SQS with visibility timeout) polls for deadlines approaching expiry and emits reminder events to the operations team and automated workflows. For fully automated responses, the system triggers evidence submission or withdrawal actions before the deadline with a configurable safety buffer (e.g., 24 hours before cutoff). Any failure to act by the deadline is logged as a compliance incident and escalates to an on-call queue. Idempotency keys on all submission API calls prevent double-submissions if the scheduler retries.