Design a Customer Payment Dispute Platform

Scenario

In an e-commerce marketplace, buyers occasionally encounter issues such as unauthorized transactions, items not received, or items significantly not as described. When informal resolution fails, buyers initiate formal payment disputes. You are tasked with designing the backend for an end-to-end Customer Payment Dispute Platform.

Requirements

Functional Requirements

1. Eligibility & Dispute Creation: Validate dispute eligibility against purchase date, order status, and existing dispute policies before opening a dispute.
2. Evidence Collection: Allow buyers and sellers to upload documents and text evidence within strict, configurable deadlines (e.g., 5 business days for seller response).
3. State Machine & Deadline Tracking: Manage dispute progression across explicit lifecycle stages (e.g., OPEN, SELLER_REVIEW, UNDER_INTERNAL_REVIEW, SETTLED_BUYER_FAVOR, SETTLED_SELLER_FAVOR, CLOSED). Automatically advance or close disputes when response windows expire.
4. Provisional Credit & Financial Settlement: Trigger provisional credits to the buyer or hold funds from seller balances, with idempotent settlements or clawbacks upon final adjudication.
5. External Processor Coordination: Coordinate dispute cases with external payment networks and gateways (e.g., card networks, PayPal) using retry-safe, idempotent interfaces.
6. Audit Trail & Notifications: Maintain an append-only, tamper-evident audit log of all events and state transitions, while notifying participants asynchronously at key milestones.

Non-Functional Requirements

• Scale: Support 50 million active marketplace users, generating 200,000 new disputes per month (~5,000 active disputes per day) with evidence uploads up to 15 MB per file.
• Consistency: Financial state updates and dispute lifecycle transitions must be strictly consistent and prevent double-refunds or duplicate provisional credits.
• Security: Evidence uploads must be sanitized and protected against malicious payloads, and sensitive customer data must remain strictly access-controlled.

What Your Design Should Cover

• Core APIs: Define endpoints for dispute initiation, evidence submission, status checks, and admin/system resolution.
• Data Model & State Management: Schema design for disputes, evidence metadata, deadlines, and state transitions.
• Architecture Diagram & Flow: System components showing intake, asynchronous worker queues, storage, and external gateway integration.
• Edge Cases & Failure Modes: Handling network timeouts during gateway callbacks, concurrent uploads, race conditions in status transitions, and storage malware scanning.