Design a payment API like Stripe
PremiumAPI designHard
- Idempotency keys
- Payment intents
- Webhooks
Quick answer
This API design interview question asks you to design a payment API like Stripe. Aim for a design that exposes a clear, consistent and safe interface, then explain the resources, requests, responses and error handling. Interviewers want to see how you name resources, version the interface and handle failure cases.
The problem
Design a payment API like Stripe: the public HTTP API that online businesses call to create, confirm, capture and refund card payments. The hard parts are retries that never charge a customer twice and a contract that keeps integrations working for years.
A merchant's server creates a payment, the customer's card is authorised, the money is captured and the merchant can later refund part or all of it. The API is the product: developers read the reference and write code against it, so every path, field, status code and error must be predictable.
What must a payment API like Stripe do?
- Payments: Create a payment for an amount and currency, confirm it with a payment method, capture it now or later (authorise, then capture within 7 days) and cancel it before capture.
- Payment methods: Tokenised cards and bank accounts attached to a customer; raw card numbers never reach the merchant's server.
How well must it do it?
- Safe retries: A merchant that times out and retries must never charge the customer twice.
- Compatibility: Integrations written three years ago keep working without code changes.
What scale should you design for?
Use these numbers in your estimates.
The scale numbers unlock with this questionUnlock
Key concepts
- Idempotency keys
- Payment intents
- Webhooks
- API versioning
- State machine
- Tokenisation
How you’ll practise
- Use cases
- Resources
- Endpoints
- Errors, auth and limits
- Versioning
- Wrap-up
Lala, personalized to you, gives a hint when you ask and reviews your design when you are ready.
What do interviewers look for?
In any API design round.
- Starts from the clients and the use cases
- Names resources and operations consistently
- Defines request and response shapes and status codes
- Covers authentication, rate limits and idempotency
- Plans pagination, filtering and versioning
- Explains how clients learn about and recover from errors
Questions people ask about this interview question
- Which design type is this question?
- It is an API design question. You design a payment API like Stripe and explain your choices the way you would in an interview.
- Is this question asked at entry level?
- It is marked Hard. It suits engineers preparing for senior interviews, where you are expected to drive the discussion and go deep on trade-offs.
- What should I cover first?
- Start with the clients, the main use cases and the resources they need. Agree on scope with the interviewer before you design anything.
- Can I practise it for free?
- It is a premium question. Sign up and unlock it once for 10 credits; it then stays unlocked. When you finish, Lala, your personalized AI mentor, can review your design for 30 credits.
Related questions
Updated · Written by the SevyDevy team