Problem statement
Design the service that takes a refund request against an order from initiation through approval, money reversal, inventory restock, and ledger posting — moving real money, so it must never over-refund.
Operating context. A refund request references an order and may be full or partial. The service checks eligibility, routes the request through approval rules (auto-approve under a threshold, manual review above it or when flagged), reverses the money through the external payment processor, restocks any returned items, and posts a ledger entry. The processor call can time out or return ambiguously, retries are inevitable, and a duplicate must never issue a second refund. State must be durable and auditable, and the service reconciles against the processor daily to catch drift. Volume spikes after peak shopping seasons: about 2000 refund requests/sec at peak, 200/sec steady.
Out of scope. The returns-merchandise-authorization and physical inspection flow, fraud investigation, customer support ticketing UI, and the payment processor's own internals. Assume the processor exposes an idempotent refund API and a reconciliation report.
What to produce. A high-level architecture covering: how a refund is modeled as a durable state machine, how approval routing and the manual-review queue work, how the money reversal is made exactly-once against an external processor, how restock and ledger posting are coordinated with the reversal, how stuck refunds are escalated, and how daily reconciliation detects and repairs drift. Sketch the components and trace a refund through auto-approve and through manual review, including a processor timeout that is safely retried.
Functional requirements
- Accept a full or partial refund request against an order and validate its eligibility.
- Route the request through approval rules — auto-approve under a threshold, otherwise a manual-review queue.
- Execute the money reversal via the external payment processor exactly once, even under retries.
- Update order state, restock returned inventory, and post a corresponding ledger entry.
- Expose refund status and history to customers and support agents.
- Reconcile refunds against the processor's daily report and flag or repair any mismatch.
Non-functional requirements
- Handle 2000 refund requests/sec at peak and 200/sec steady.
- Never double-refund: exactly-once money movement across retries and duplicate requests.
- Refund state transitions are durable and fully auditable; daily processor reconciliation closes the loop.
- 99.95% availability; a refund stuck in a non-terminal state escalates within 24 h.
- Retain refund and ledger records 7 years (~20 TB) with immutable history.
Topics
- System Design HLD
- Commerce Payments
- Patterns State-Machine
- Reliability Idempotency
- Compliance Audit