Design a Payment System That Charges Customers Through an External Payment Provider

Design a payment system that lets an online product charge its customers. Product services such as checkout and billing ask the payment system to collect money. The payment system charges the customer's payment method through an external payment service provider (PSP), tracks every payment to a final outcome, and keeps an accurate, auditable record of all money that moved. The interview reported only the topic, so the scope below is the standard implied scope for this prompt. Confirm it through the clarifying questions before you design. Assume the system must support: - **Charge**: a product service asks for a given amount in a given currency to be charged to a customer for a specific order or invoice. - **Completion**: the PSP reports the outcome either in its API response or later through a webhook callback. - **Refund**: a completed charge can be refunded in full or in part. - **Status and history**: internal services and support staff can look up any payment and its history. ```hint Follow a timed-out charge Trace a charge whose call to the PSP times out: the customer may or may not have been charged. Decide what the system must record before and after that call so that every retry, by any component, is safe. ``` ```hint Prove where the money went Think about how you would show, months later, exactly how much a customer paid and was refunded, and how you would detect that your records and the PSP's records disagree. ``` ### Constraints and Clarifications - Assume raw card numbers and bank details are collected and stored by the PSP. The payment system stores only the PSP's tokens and references. - A customer must never be charged twice for one order, even when the calling service, the payment system or the PSP retries. - Amounts must be exact; no rounding error is acceptable anywhere on the money path. ### Clarifying Questions - Is this a payment backend for one company's own product, or a platform that external merchants integrate with? - Are charges one-off purchases, recurring subscriptions, usage-based invoices, prepaid credits, or a mix? - What peak rate of payments, which currencies and which regions must be supported? - Does the customer wait on a checkout screen for the result, or can a payment complete asynchronously? - Does the system only collect money, or must it also pay money out to sellers or partners? - Is there one PSP, or several with routing or failover between them? ### What a Strong Answer Covers - Scope and priorities stated up front: correctness and durability of money records ahead of raw throughput - An explicit payment state machine, including the "outcome unknown" state that a PSP timeout creates - Exactly-once charging end to end: idempotency at the API, inside the workflow, and on the PSP call - An append-only, double-entry record of money movement, and reconciliation against the PSP's reports - Concrete APIs, a data model, and both the synchronous and the webhook-driven completion paths - Failure handling for timeouts, PSP outages, crashed workers, and duplicate or out-of-order webhooks - Security boundaries around payment credentials, and the metrics that reveal stuck or mismatched payments ### Follow-up Questions - How would you add a second PSP and route or fail over between providers without ever double-charging? - The nightly reconciliation finds a charge that the PSP captured but your database marks as failed. How did that happen, and how does the system repair it? - How would you support recurring subscription billing on top of this design? - How do partial refunds, refund requests larger than the remaining balance, and chargebacks fit into the state machine and the ledger?