Design an Idempotent Payment Processing Platform

# Design an Idempotent Payment Processing Platform Design a payment processing platform that accepts a payment request, interacts with an external payment provider, records the result, and exposes status to the caller. Focus on idempotency, retry behavior, and failure handling when a network timeout leaves the provider outcome unknown. ### Constraints & Assumptions - A client may retry the same logical payment after a timeout. - The external provider may complete a charge even when the platform does not receive its response. - Money is represented in an exact minor unit with currency attached. - Payment history and state transitions must be auditable. - Exact scale, settlement flow, refund scope, and consistency targets should be clarified. ### Clarifying Questions to Ask - Is the endpoint authorizing, capturing, or immediately charging a payment? - Who creates the idempotency key, and for how long must it remain effective? - Does the provider support its own idempotency key and status lookup? - Which states may a client observe while the provider outcome is unresolved? - Are refunds, partial capture, multiple currencies, and webhook events in scope? ### What a Strong Answer Covers - A payment record keyed by merchant and idempotency key, with a hash of immutable request fields. - An explicit state machine including unresolved outcomes rather than treating every timeout as failure. - Transactional creation, concurrency control, and replay of the original response for duplicate requests. - Provider calls carrying a stable downstream idempotency key and bounded retries by error class. - Reconciliation through provider lookup, webhooks, or scheduled polling when the response is ambiguous. - Ledger or immutable transition history, exact money handling, access control, and protection of sensitive payment data. - Queue, outbox, backpressure, availability, observability, and safe operator repair without a second charge. ### Follow-up Questions 1. Two identical requests with the same idempotency key arrive concurrently. Which database operation prevents two provider calls? 2. The same key is reused with a different amount. What response should the platform return? 3. The provider times out after charging the card. Why is an immediate retry unsafe without provider idempotency? 4. How do webhooks and polling update the same payment without racing into contradictory states? 5. What information belongs in an immutable payment ledger versus a mutable status projection?