A payment request times out. The client does not know whether the charge went through, and the customer is still waiting. Retrying blindly can charge the card twice; giving up can lose a sale that actually succeeded. Idempotency keys in a payment API solve this one problem: the client attaches a unique key to the request, and if it sends the same request again with the same key, the provider returns the earlier result instead of doing the work a second time.
Stripe, Adyen, PayPal and Square all support the pattern, but they differ on where the key goes, how long it lives, what a replay returns and what happens when two copies arrive at once. Those details decide whether a retry is safe.
Why POST needs help
HTTP already defines some methods as idempotent. RFC 9110, the HTTP semantics standard, says PUT, DELETE and the safe methods such as GET have the same intended effect whether a request is sent once or several times. POST is not on that list, and creating a payment, a refund or a capture is almost always a POST.
A key turns that POST into something a client can repeat. Stripe’s documentation says all API v1 POST requests accept idempotency keys, while sending one with GET or DELETE in API v1 has no effect. Adyen says the same for its POST endpoints and treats GET, DELETE and PUT as idempotent already.
The IETF’s HTTP API working group is drafting a standard Idempotency-Key header for exactly this use. The Internet-Draft is active: version 08 was posted on October 22, 2026 and expires on April 25, 2027 unless it is replaced or advanced. It is still a draft, not an RFC, so each provider’s documentation remains the rulebook.
Four providers, four sets of rules
| Where the key goes | Length limit | How long it is kept | |
|---|---|---|---|
| Stripe | Idempotency-Key header | 255 characters | At least 24 hours in API v1; replays count within 30 days in API v2 |
| Adyen | idempotency-key header | 64 characters | 7 to 14 days after first submission |
| PayPal | PayPal-Request-Id header | 38 single-byte characters (a UUID fits) | Set per API; check the endpoint reference |
| Square | idempotency_key field in the request body | 45 characters on CreatePayment | Not stated on the general page |
Stripe (API v1) saves the status code and body of the first request made with a key once the endpoint begins executing, whether it succeeded or failed, and returns that same result to later requests with the key, including 500 errors. A replayed response carries the header Idempotent-Replayed: true, which tells your code it is looking at a stored answer. Stripe compares incoming parameters with the original and returns an error saying the request did not match if they differ. Keys are kept for at least 24 hours and can be removed after that; a key reused after removal can execute a new request. Stripe suggests V4 UUIDs and warns against putting email addresses or other personal identifiers in a key.
Stripe’s newer API v2 endpoints behave differently. Per the API v2 overview, repeating a request that succeeded returns an updated response without new changes, repeating one that failed is executed again, and a replay must use the same key, API and account within 30 days. Check an endpoint’s namespace before reusing v1 retry logic.
Adyen stores keys at the company account level and treats them as valid for 7 to 14 days after first submission. A key used against one regional endpoint is not checked for duplicates in another region. Adyen echoes the idempotency-key header in its response when it handled a request idempotently. It recommends a random version 4 UUID per request partly for security: two API credentials under the same account could otherwise read each other’s stored responses.
PayPal uses its own header, PayPal-Request-Id, and its idempotency reference notes that not every API supports it; each endpoint’s reference states support and how long the ID is stored. In the current Orders v2 and Payments v2 schemas, the header is listed on create order, authorize order, capture order, capture authorization, reauthorize, void and refund. One difference matters for reconciliation: PayPal returns the latest status of the earlier request, not a frozen copy of the original response. Omit the header and PayPal processes the request again. The value must be unique per request and per call type, so an authorization and its capture need different IDs.
Square puts the key in the request body. On CreatePayment idempotency_key is a required field of up to 45 characters. Square’s idempotency guide says a repeated request with the same key returns the first successful response, while the same key with a changed request, such as a different amount, returns an error, though behavior “might vary depending on the API.” Square also offers a way out when a CreatePayment response never arrives: cancel payment by idempotency key voids the payment created under that key (or does nothing if none exists), after which the payment can be submitted again.
These are the providers’ current documented rules. For dated version changes and retirements by provider, see our payment API changelog tracker, and for how each provider ships breaking changes, our comparison of payment API versioning models.
When two requests arrive at once
Retries are not always sequential. A client with an aggressive timeout can send a second copy while the first is still running.
Stripe does not save a result for a request that conflicts with another request already executing under the same key. Its error handling guide says that when a 409 shows another request with the same key is still running, the client should wait and retry with that key and the same parameters, because a new key can start a second operation.
Adyen answers a duplicate that arrives before the first has finished with HTTP 422 or 409 and error code 704, “request already processed or in progress.” When Adyen’s response carries a transient-error: true header, the request can be retried later with the same key; without that header, or with the value false, Adyen says not to retry. PayPal says it processes the first of two simultaneous requests with the same ID and might fail the second.
Adyen also documents a rare failure of its own idempotency store, signaled by HTTP 503 with error code 703, “required resource temporarily unavailable.” Its advice is to pause and retry later or, if those errors pile up, to fall back to sending requests without the header.
Which errors to retry with the same key
Stripe’s current advanced error handling guide for API v1 sorts failures into three groups, and it is strict about when a new key is allowed.
- Network errors and timeouts. This is the case keys were built for. Retry with the same key and the same parameters, but only within the first 24 hours after the original request. If the outcome is still unknown after that, stop retrying with either the old key or a new one, and reconcile: retrieve the object, inspect the request in the Dashboard and check webhook events.
- Content errors (4xx). Stripe caches a result once the API method begins executing, so a cached
400comes back unchanged under the same key. Errors raised before execution, such as invalid parameters, an invalid API key or a429rate limit, cache nothing and can be retried once fixed. Stripe now says to choose the next step from the error instead of generating a new key for every 4xx. Use a new key for a corrected request only after you have established that the original did not succeed and is not still running. - Server errors (500). Stripe caches these too, so the same key returns the same
500while the key is retained. Treat the result as indeterminate, do not switch to a new key until the original outcome is resolved, and expect webhook events for objects Stripe creates while reconciling an incident.
Stripe responses can also carry a Stripe-Should-Retry header: true means retry with backoff, false means do not retry. Both Stripe and Adyen recommend exponential backoff between retries. How to pace retries when a provider throttles you is covered in our explainer on payment API rate limits. Stripe’s SDKs can generate keys and retry automatically once configured, but a retry that spans separate SDK calls or a process restart needs a key your application generates and stores. PayPal’s REST SDKs handle the header for you.
A short checklist
- Generate the key once per logical operation, before the first attempt, and store it with the order or payment record so a restarted worker reuses it.
- Use a random UUID. Never build keys from customer data.
- Reuse the key only with identical parameters. A changed amount is a new operation.
- Match your retry window to the provider’s: a queue that retries after two days outlives Stripe’s 24-hour v1 window, while Adyen keeps keys for at least a week.
- Give each step its own key. An authorization, its capture and any refund are separate operations, and PayPal requires separate IDs for them.
- Treat a key as protection for one request, not as reconciliation. Webhooks, once you verify their signatures and handle their retries, and a final status lookup still confirm what happened.
Adyen adds one more safeguard that keys do not replace: its accounting rules prevent capturing more than the authorized amount or refunding more than was captured, by default. A key prevents a duplicate request. It does not prove the first one did what you expected.





