Design a donation payment API for a fundraising event: flow, endpoints, failure handling

You are the product manager responsible for the payment API behind a charity event that collects donations. Design it: define what the API must support, walk through how a donation travels from the donor to the charity, and outline the main endpoints with the data each one accepts and returns. ```hint Follow one gift end to end Trace a single donation from the moment someone decides to give until the charity can count the money, and note every party it passes through. Each handoff suggests an endpoint you need and a way the gift can go wrong. ``` ### Clarifying Questions - Is the event in person, online or both, and how does a donor reach the payment step: a link, a QR code at the venue, or a ticketing page? - Which payment methods, currencies and countries must work at launch, and does the charity already use a payment processor or expect to connect to banks directly? - Are gifts one-time only or also recurring, and can donors give anonymously or ask for a receipt? - Which clients call the API (the charity's donation page, staff devices at the venue, partner apps), and how many donations should it handle at the busiest moment? ### What a Strong Answer Covers - Requirements scoped from the clarifications: callers, payment methods, currencies, one-time versus recurring, anonymity and receipts - An end-to-end donation flow that relies on a payment processor rather than handling raw card data, with each party's role - Concrete endpoints and resources (create, status, processor callback, refund, reporting) with their key request and response fields - Correctness under failure: idempotency against double charges, retries, verified callbacks, and reconciliation with the processor and the bank - Security, fraud and compliance at a public event, plus metrics such as donation completion rate ### Follow-up Questions - The venue's network drops just as a donor taps Donate, and they tap again. How do you make sure they are charged once? - How would you add monthly recurring gifts without breaking existing callers? - What would the organizer's live totals screen show, and how would you keep its numbers accurate?