Design Payment Processing with Idempotency and Reconciliation

Design a payment-processing service. It accepts payment requests from clients, sends them to an external payment provider, records each outcome durably, and recovers correctly from client retries, provider timeouts, and asynchronous status updates. ```hint Preserve uncertainty explicitly A timeout after the request is sent does not prove that the provider failed to process it. ``` ### Constraints and Clarifications - The payment methods, currencies, volume, authorization and capture model, refunds, and settlement requirements are not specified. State the scope and scale you assume. - Keep the guarantees your own service can enforce separate from behavior that depends on the external provider. ### Clarifying Questions - Is a payment one step, or split into authorization and capture? - What identifies one logical payment, and how should a duplicate request be recognized? - Which status changes does the provider report asynchronously, and can those reports arrive late, twice, or out of order? - Are refunds, partial amounts, and multiple currencies in scope? ### What a Strong Answer Covers - Requirements, volume estimates, and APIs for creating a payment, reading its status, and receiving provider updates. - A stable payment identity, exact amounts, a durable state machine, and idempotent handling of client retries and provider calls. - Handling of timeouts, webhooks, and reconciliation, with at least one weighed alternative. - Partitioning and scaling, concurrency control, audit trail, and monitoring. ### Follow-up Questions - How do you handle a success webhook that arrives after the client has already retried the request? - What happens if a refund request races with a capture event for the same payment? - How would you add a second payment provider without duplicating the state logic?