Design an Idempotent Payments API

Square's real Payments API takes an idempotency_key as a field in the request body, and the timed-out payment is the failure it exists to absorb. The setup is concrete. A seller dips a card on a Square Reader or checks out online, and the app posts a payment. The request reaches the server and the authorization succeeds. Then the response is lost coming back. A timeout. The app now has no idea whether the buyer was charged. Retry blindly and it charges twice. Give up and it may have taken money for a sale it cannot confirm. That single failure, a lost response over an unreliable network, is the problem in full, and idempotency is the answer.

Start by naming what is and is not achievable. Exactly-once delivery over a network is impossible: any message can be lost, and the sender can never tell a lost request apart from a lost response. So we aim for the next best thing. The seller's app retries until it gets an answer, which gives us at-least-once delivery, and the server makes processing idempotent, so a repeated request produces the same single result. At-least-once delivery plus idempotent processing gives you effectively-once, the property money movement needs. Say that out loud early. It frames every decision that follows.

The Block angle

Square puts the idempotency key in the request body, not in a header the way some processors do, and a repeated key returns the original payment instead of charging again. That is a documented public contract on POST /v2/payments, so put the key on the write path before anyone asks for it. Block's pitch to sellers is economic empowerment, which in engineering terms means never quietly losing or double-taking a small merchant's money. The panel rewards explicit engagement with the fintech specifics. A candidate who opens with throughput math has misread the round. Open with the lost response.

BlockPremium lesson · System design round

The Block design, worked end to end.

1. 1The API and data modelSystem design · Frequently asked
2. 2The design, drawn out3 diagrams
3. 35 deep divesWith the tradeoffs

Get the Block questions

$49 a year · all 100 companies · cancel anytime

From 20,000+ candidate reports, forum threads behind logins and write-ups in Chinese.

Read a free Block lesson firstAlready a member? Sign in