Fintech Development

Idempotent Payment Endpoint Prompt

Design an idempotent payment processing endpoint with key strategy, race-condition handling, and a retry-safe API contract.

Anselm Fowel / Public collection29 Sept 2026

Your prompt

The prompt

You are a staff backend engineer who has built payment processing endpoints handling millions of transactions a day for a [PAYMENTS COMPANY TYPE, e.g., PAYMENT PROCESSOR / NEOBANK / MARKETPLACE]. You have personally debugged double-charge incidents caused by naive retry logic and know exactly where idempotency breaks down in production.

I'm building a payment processing endpoint in [LANGUAGE/FRAMEWORK] backed by [DATABASE]. It accepts [TRANSACTION TYPE, e.g., CARD CHARGES / ACH DEBITS / WALLET TRANSFERS] and must be safe to retry from [CLIENT TYPE: MOBILE APP / PARTNER API / INTERNAL JOB]. Payment amounts are stored as [CENTS AS INTEGERS / DECIMAL TYPE] in [CURRENCY].

First, design the idempotency key strategy: where the key comes from, how long it's retained, what happens when the same key arrives with a different payload, and how you detect a genuinely duplicate request versus a client bug. Explain the exact database-level mechanism (unique constraint, conditional write, or distributed lock) that prevents two concurrent requests with the same key from both succeeding.

Next, write the endpoint's request handling logic showing the full state machine: request received, in-flight, succeeded, failed, and how each state responds to a retry. Include what HTTP status code and response body each state returns, especially the case where a retry arrives while the original request is still in-flight to the [PAYMENT PROCESSOR/GATEWAY].

Then list the 7 edge cases most likely to cause a double charge or a stuck transaction in this design, including client timeout before response arrives, processor timeout after the charge actually succeeded, and process crash mid-transaction. For each, state the specific failure mode and the mitigation.

Finally, write the core endpoint function in [LANGUAGE/FRAMEWORK] with inline comments explaining every idempotency-relevant decision, followed by a table of the edge cases with columns: Scenario, Root Cause, Mitigation, and Test Case to verify it.

2,007 characters

Your prompt

Recent articles