iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
For Stripe, sending a different amount with the same idempotency key is not a valid retry: Stripe compares the new request’s parameters with the original and returns an idempotency error when they differ. The exact behavior is provider- and endpoint-specific, so do not assume every payment API handles a changed amount the same way.
What happens when the amount changes?
An idempotency key lets an API recognize retries of the same logical request. It is not a way to edit or replace the operation attached to an existing key. If a payment attempt is uncertain because a connection failed, retry the unchanged request with its original key. If the amount or other request details have changed, treat it as a new operation and use a new key, following the provider’s documentation.
For Stripe, a changed amount is a parameter mismatch. Stripe says its idempotency layer compares incoming parameters with those of the original request and errors when they are not the same. See Stripe’s idempotent requests documentation and its idempotency error reference.
Free tools Windows power users keep installed
One-click scans. No signup required.
Does the API return the same response?
That depends on the provider and whether the first request reached the point where its result is recorded. For Stripe, once endpoint execution begins, the first status code and response body are saved; subsequent requests with the same key and matching parameters return that result. The saved result can itself be an error. Validation failures that happen before execution, and certain conflicts with concurrent requests, are not saved as idempotent results.
#1 Best Overall
So “same key, same response” describes a replay of a recorded result for a matching request—not a guarantee that a modified request will repeat the original response or update the original payment.
How Stripe, Adyen, and PayPal differ
The table summarizes the documented behavior in the cited guidance. PayPal’s documentation does not establish one universal response to a changed amount across all supported endpoints.
| Provider | Replay and changed-parameter behavior | Scope and retention |
|---|---|---|
| Stripe | Replays the first status and body for matching requests after endpoint execution begins. A request whose endpoint or parameters differ from the original produces an idempotency error. | Keys may be removed once they are at least 24 hours old. Validation failures before execution and certain concurrent conflicts are not stored as idempotent results. Stripe documentation; error reference. |
| Adyen | For a processed request retried with the same key, returns the first response without duplicating the action. The cited guidance does not specify a universal changed-amount response. | Applies to POST requests; keys are scoped to a company account and valid for 7 to 14 days. Concurrent requests can return a transient error or an in-progress/processed conflict. Adyen documentation. |
| PayPal | For supported REST calls, reusing the same PayPal-Request-Id returns the original result while the ID is stored. The cited guidance does not establish a universal changed-amount response across endpoints. |
Stored for up to 45 days, and support must be checked for the specific API call. PayPal idempotency guidance; REST request guidance. |
What to do when a payment request needs a different amount
- If the original request may have succeeded but the response was lost: retry the same logical request with the same key and unchanged parameters, as the provider documents.
- If the amount has genuinely changed: create a new logical request and use a new idempotency key. Do not rely on reuse of the old key to change the payment.
- If requests overlap: follow the provider’s concurrency and error-handling guidance. A response indicating that work is in progress or conflicting is not necessarily the final outcome of the operation.
- If you use an API other than Stripe: check the documentation for the exact endpoint and key header or request field. Confirm whether idempotency is supported there, how parameter mismatches are handled, when results are stored, and how long keys are retained.
Why key retention matters
Idempotency keys are not necessarily permanent records. Stripe may prune keys once they are at least 24 hours old; Adyen documents a 7-to-14-day validity period; PayPal says it stores request IDs for up to 45 days. These are provider-specific retention rules, not a shared industry standard. After a key is pruned or expires, a later request using it may be treated as new, depending on the provider’s rules.
Quick Recap
Rank #3
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
