Design a Payment API
You'll learn to
- -Combine idempotency keys, a refund sub-resource, precise error codes and webhooks into one coherent design
- -Run charge, retry, decline and partial refunds, and watch money move exactly once
- -Say why a payment design is append-only and conservatively versioned
Payment APIs are a favorite system design prompt because correctness matters more here than almost anywhere. A subtle mistake does not just produce a wrong API response. It can mean a customer charged twice, or a merchant never credited for a real sale.
An Analogy: The Bank Counter Slip
At a bank counter, a cashier gives you a numbered slip for each transaction and writes it in the ledger. If you come back and say "slip 482, did that go through?", they look it up instead of doing it again. Refunds are separate entries that point back at the original slip. Nothing in the ledger is ever erased. The payment API below works the same way.
Step 1-2: Clients and Resources
Clients: a merchant's backend that charges customers, and internally a reconciliation and reporting system. Core resources: Payment (one charge attempt), Refund, and Customer (for stored payment methods of returning customers).
Step 3: Protocol, REST, Deliberately
REST fits. Payments are naturally resource-shaped: create a payment, look one up, issue a refund against one. The clients are mostly server-to-server integrations that do not need GraphQL's flexible querying. And REST's status codes map cleanly onto payment outcomes.
Step 4: The Contract, Combining Techniques From Across This Course
- -POST /v1/payments: charge a customer (an idempotency key is required).
- -GET /v1/payments/{id}: look up one payment's current status.
- -POST /v1/payments/{id}/refunds: issue a full or partial refund against a payment.
- -GET /v1/payments/{id}/refunds: list the refunds issued against a payment.
- -POST /v1/customers: create a customer record for a returning payer.
- -POST /v1/customers/{id}/payment_methods and GET ...: attach and list stored payment methods.
POST /v1/payments
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{
"amount": 4999,
"currency": "usd",
"customer_id": "cus_42",
"payment_method_id": "pm_501"
}
HTTP/1.1 201 Created
{
"id": "pay_501",
"status": "succeeded",
"amount": 4999,
"currency": "usd"
}A retried payment request, from a network timeout, a client crash or anything else, must never charge twice. The idempotency-key discipline from earlier in this course is not a nice-to-have here. It is the detail most likely to come up as a pointed follow-up, precisely because getting it wrong means a real financial error.
POST /v1/payments/pay_501/refunds
Idempotency-Key: a1b2c3d4-1111-2222-3333-444455556666
{
"amount": 1999,
"reason": "requested_by_customer"
}
HTTP/1.1 201 Created
{
"id": "re_88",
"payment_id": "pay_501",
"amount": 1999,
"status": "succeeded"
}A refund gets its own idempotency key, since retrying the same refund request must not refund twice, and its own resource under the payment. One payment can have several partial refunds. A mutable status field on the payment would lose that history and turn "how much has been refunded so far?" into an error-prone sum instead of a simple query.
HTTP/1.1 402 Payment Required
{
"type": "https://api.example.com/errors/card-declined",
"title": "Card Declined",
"status": 402,
"detail": "The card was declined by the issuing bank.",
"decline_code": "insufficient_funds"
}A declined card is not a 500, because nothing failed on the server. It is not a generic 400 either, because the request was perfectly well formed. It is a legitimate business outcome that deserves its own specific status and detail, following the RFC 7807 error-design discipline. The decline_code lets the client give the customer a genuinely helpful message, such as "insufficient funds", and not just "payment failed".
The demo plays a small story. It charges a card and retries, tries a declined card, and issues partial refunds up to the full amount. Watch the stored count, the replayed responses and the last refund being refused.
POST https://merchant.example.com/webhooks/payments
X-Webhook-Signature: sha256=...
{"event": "payment.succeeded", "payment_id": "pay_501"}Some payment methods, such as bank transfers and fraud-review holds, do not resolve within the original request. The first response might be status: "pending", with a signed webhook telling the merchant once the payment settles or fails. It is the long-running-operation shape from earlier, applied to settlement.
Step 5: Evolution and Auditability
Payment records should be append-only, or event-sourced, for audit, like the financial ledger chapter. A payment's whole history (attempted, succeeded, later refunded) must be reconstructable, not just its current state. On versioning, a carelessly deployed breaking change has real financial consequences, which makes the deprecation-with-a-real-timeline discipline non-negotiable here.
In a real interview, naming the idempotency requirement before the interviewer asks about retries or duplicate charges is one of the strongest single signals in this course's case studies. It shows the money-handling instinct the prompt is testing.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design a Payment API in the API Design Lab's Full System Design act.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!