Skip to content
API Design Learn/Capstone Case Studies
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Design a Payment API

5 min read

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.
Idempotency is not optional here - it is the single most important detail
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.

Refunds are their own sub-resource, not a field mutated on the payment
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.

Specific, actionable error responses for payment failures
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.

Press Run: the retry and the repeated refund change nothing, and a refund over the total is refused
Webhooks for asynchronous status changes after the initial request
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.

Ready to Build This?

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.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!