## Design a Payment Orchestration System Design the merchant-side service that coordinates payment authorization, capture, refund, and status tracking through one or more external payment processors. Do not implement a card network or bank ledger. Focus on preserving a correct business record when requests, callbacks, and retries can all be duplicated or delayed. ### Constraints & Assumptions - A checkout may authorize and capture immediately or capture later. - Processor calls can time out after the processor has accepted the operation. - Webhooks are untrusted, duplicated, and potentially out of order until verified. - Money uses integer minor units and an explicit currency. - Do not assume volume, processor count, settlement delay, or availability targets; state how they affect the design. ### Part 1 — Define Commands and Payment State Specify APIs and a state machine for creating a payment, authorizing, capturing, refunding, and reading status. Explain idempotency and which transitions are legal. #### What This Part Should Cover - Merchant, order, payment, operation, and processor-reference identities. - Idempotency keys scoped to the caller and operation. - Amount, currency, attempt, and state-transition validation. - Separate command acceptance from the processor's final outcome. ```hint Model operations, not only one status field A payment can have several capture or refund attempts whose histories must remain distinguishable. ``` ### Part 2 — Preserve Financial Consistency Design the durable write path and accounting records. Explain how the system avoids double capture or refund while retaining an auditable history of every request and outcome. #### What This Part Should Cover - Append-oriented payment operations and immutable accounting entries. - Transactional state changes plus an outbox for external work or events. - Invariants such as captured amount not exceeding authorized amount and refunds not exceeding captured amount. - Reversal or compensating records instead of rewriting financial history. ```hint Keep intent and outcome separate A timed-out call still has a recorded intent even when the processor outcome is initially unknown. ``` ### Part 3 — Integrate with Processors and Recover Failures Handle ambiguous timeouts, retry, webhook verification, out-of-order events, provider outage, and reconciliation with processor reports. #### What This Part Should Cover - Stable operation identifiers sent to processors that support idempotency. - An `UNKNOWN` or pending reconciliation path instead of an unsafe blind retry. - Signature verification, replay protection, deduplication, and monotonic transition rules for webhooks. - Scheduled reconciliation that compares internal operations with processor truth. ```hint A timeout is not a decline Before retrying a money-moving command, determine whether the first attempt may already have succeeded. ``` ### Part 4 — Secure and Operate the Platform Discuss sensitive-data boundaries, access control, multi-processor routing, observability, and safe deployment. #### What This Part Should Cover - Tokenization and avoidance of raw payment credentials in application storage and logs. - Least-privilege administrative access and evidence for manual actions. - Routing and failover rules that do not duplicate a possibly completed operation. - Metrics for pending age, reconciliation mismatch, duplicate callbacks, declines, refunds, and processor errors. ```hint Audit manual recovery An operator correction can move money or change what a customer sees, so it needs the same traceability as an automated command. ``` ### What a Strong Answer Covers - Explicit payment and operation state machines with enforceable amount invariants. - End-to-end idempotency across client retries, internal jobs, processor calls, and webhooks. - Safe handling of unknown outcomes and delayed or out-of-order callbacks. - Immutable accounting history, reconciliation, security boundaries, and operational recovery. - Trade-offs tied to the stated processor and workload assumptions. ### Follow-up Questions 1. How would you capture an authorization in several partial amounts? 2. What should happen if a refund request times out and its webhook arrives after a retry attempt? 3. How would you migrate an active merchant from one processor to another? 4. Which records would you use to explain a payment dispute months later?