Chiavi di idempotenza, addebiti esattamente una volta, nuovi tentativi sicuri dopo un timeout.
Spec — Idempotent payments
Status: draft · Created: 2026-11-10
1. Context and goal
A client that loses the answer to a payment request can send it again without ever charging the customer twice.
2. Functional requirements (EARS)
- FR-1: THE SYSTEM SHALL require an
Idempotency-Keyheader of 1 to 255 characters on every request that creates a charge or a refund, and answer 400 without it. - FR-2: WHEN a key is first seen, THE SYSTEM SHALL store it with the caller and a hash of the request body, in the same transaction as the charge intent, before calling the payment provider.
- FR-3: WHEN a request repeats a key whose first request has finished, THE SYSTEM SHALL return the stored status code and body without calling the provider again.
- FR-4: IF a request repeats a key with a different body, THEN THE SYSTEM SHALL answer 422 and charge nothing.
- FR-5: IF a request repeats a key whose first request is still running, THEN THE SYSTEM SHALL answer 409 with
Retry-After: 1. - FR-6: IF the provider call times out after 30 seconds, THEN THE SYSTEM SHALL look the charge up at the provider by the same key, which it passes on every call, before any retry.
- FR-7: THE SYSTEM SHALL keep keys for 24 hours, and compare its charges with the provider's every hour, alerting on any mismatch.
3. Out of scope
- Idempotency of endpoints that do not move money.
- Currency conversion.