An idempotency key is a unique identifier for one logical payment operation. Send it with the initial request, save it with your local payment record, and reuse the same key and equivalent parameters whenever a timeout or lost response leaves the outcome uncertain. The API can then recognize the retry and avoid executing the charge again, usually by returning the first result. The exact retention period, header name, endpoint coverage and duplicate-response behavior depend on the provider.
Why a payment retry can charge twice
Payment requests can reach a provider even when your application never receives the response. A mobile connection may drop after the server accepts the request, a proxy can time out while the provider is still working, or a worker can restart after sending bytes but before recording the result. From the client’s perspective, the operation is unknown: it may have failed, or it may have succeeded.
As an Amazon Associate I earn from qualifying purchases.
If the client sends a second request as a new operation, the provider may see two legitimate charge requests. A cardholder can then be authorized twice even though the customer clicked “Pay” only once. An idempotency key gives both requests the same operation identity. When the provider supports that key for the endpoint, it can recognize the second request as a retry rather than a new payment.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallThis mechanism protects the request side effect; it does not prove that every downstream system has exactly one state change. You still need payment-status reconciliation, webhook processing and a policy for uncertain or pending results.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
The idempotency contract
One key represents one logical operation
Create a new high-entropy key for each new payment operation. Reuse that key for every retry of that operation, including retries performed by a background worker after a process restart. Generate a different key when the customer intentionally starts a separate payment, even if the amount and card are identical.
Stripe recommends a v4 UUID or another random value with enough entropy, and Adyen recommends a v4 UUID. A UUID is an identifier, not a secret: do not put card numbers, email addresses or predictable order counters into it. Keep the key opaque and unique within the scope required by the provider.
Persist before sending
Store the key beside your local payment record before making the outbound request. A minimal record can contain operation_id, idempotency_key, amount and currency, provider, request fingerprint, status, provider payment ID, attempt timestamps and the latest response metadata. Put a uniqueness constraint on the local operation identifier and, where appropriate, on the key so two workers cannot create separate keys for one operation.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
This storage pattern is an implementation safeguard derived from the providers’ requirement to reuse a key. It lets a restarted worker recover the original key instead of accidentally creating a second transaction.
Retry with the same parameters
When the outcome is uncertain, resend the request with the identical key and the same logical parameters. Do not change the amount, currency, customer, capture setting or other fields merely because the first response was lost. Stripe explicitly compares parameters associated with an existing key and returns an error when they differ. Other providers may apply different checks, so treat a key and its request data as an inseparable pair.
POST /payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{"amount":4999,"currency":"usd","order_id":"order_123"}If the customer changes the order total or chooses a different payment method, that is a new logical operation. Create a new key and retain an audit link to the previous attempt rather than mutating the old operation.
How major payment APIs implement idempotency
Header names, endpoint support, retention and duplicate responses are not standardized across providers. Confirm the contract for the exact API operation and account type you use.
| Provider | Header and methods | Key limits and retention | Duplicate and retry behavior |
|---|---|---|---|
| Stripe | Idempotency-Key; all POST requests accept keys. GET and DELETE require none because Stripe treats them as idempotent by definition. |
Maximum 255 characters. Keys may be removed after they are at least 24 hours old. | After endpoint execution begins, Stripe stores the first status code and body, including a 500 response, and replays them for later requests with the key. Changed parameters produce an error. Validation failures and certain concurrent conflicts are not saved as results. |
| Adyen | idempotency-key; documented for POST requests. |
Maximum 64 characters. Keys are unique at company-account level and valid for 7 to 14 days. | A duplicate arriving while the first request is in progress can return HTTP 422 or 409 with error code 704. Retry later with the same key only when the response identifies a transient error; use exponential backoff. |
| PayPal | PayPal-Request-Id; recommended for POST and PUT, with support verified for each endpoint. |
Developer documentation says request IDs are stored for up to 45 days. | While the ID is stored, a repeated call with the same ID is recognized as a duplicate and returns the original call result. |
These windows are provider documentation, not universal guarantees. A key reused after the provider has pruned it can be interpreted as a new operation. Stripe explicitly documents that reusing a key after pruning can create a new request. Adyen’s 7-to-14-day validity and PayPal’s up-to-45-day storage are also bounded operational windows, not permanent records.
A reliable implementation, step by step
- Create an internal payment operation. Assign your own immutable operation ID when the customer confirms payment. Record the amount, currency, order and intended action.
- Generate and save the key. Generate a cryptographically random UUID v4 (or an equivalent high-entropy string), save it with the operation, and commit that record before the outbound API call.
- Build a deterministic request. Serialize the same amount, currency, customer and operation options for every retry. Save a request fingerprint or canonical payload so your worker can detect accidental changes.
- Send the provider request. Put the key in the provider’s documented header. Confirm that the endpoint supports idempotency; a header on an unsupported endpoint is not protection.
- Record the response atomically. Save the provider status, provider payment identifier, response body or relevant fields and timestamps. Mark the local operation succeeded, failed or pending according to the provider’s semantics.
- Handle an uncertain result. If the connection fails after transmission, leave the operation in an unknown or pending state. Retry with the saved key and identical parameters, not with a newly generated key.
- Stop on a definitive outcome. A replayed success, a documented permanent error or a provider status that requires customer action should end automatic retries. Preserve the complete attempt history for support and reconciliation.
- Reconcile asynchronously. Consume the provider’s server-to-server webhooks or status APIs and correlate events with the operation and provider payment ID. This closes gaps when the final HTTP response never reaches your application.
Choosing when and how to retry
Idempotency makes a retry safe to identify, but it does not make every error retryable. Classify the response before scheduling another attempt.
Rank #4
| Situation | Action | Key handling |
|---|---|---|
| Connection timeout, dropped response or worker crash after send | Assume the request may have reached the provider. Retry after a bounded delay, then verify status through the provider’s documented mechanism. | Reuse the original key and equivalent parameters. |
| Provider says the request is still processing | Wait and poll or await a webhook. Do not create a second payment while the first is unresolved. | Keep the same key for any permitted retry. |
| Adyen duplicate/in-progress response with HTTP 422 or 409 and code 704 | Inspect the documented transient-error signal. Retry later only when it marks the case as transient; otherwise resolve through status checking or support procedures. | Reuse the original key when a retry is allowed. |
| Validation or authentication failure | Fix the request or credentials. Repeating the unchanged invalid request usually cannot succeed. | Do not rotate the key to hide a malformed request; start a new key only after creating a genuinely new operation. |
| Parameter mismatch for an existing key | Stop and investigate the local state. The amount or other operation data has diverged. | Never reuse that key with the changed payload. |
Use bounded exponential backoff with jitter so many workers do not retry simultaneously. Adyen specifically recommends exponential backoff and advises using its transient-error indication to decide whether a duplicate response is retryable. A practical schedule can increase delays between attempts and impose a maximum elapsed retry period, but the exact values should follow your provider’s rate limits and incident policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Retention windows are part of your design
Idempotency state lives on the provider for a finite period. Stripe documents pruning after keys are at least 24 hours old; Adyen documents validity of 7 to 14 days; PayPal documents storage for up to 45 days. The provider may also scope uniqueness differently: Adyen documents uniqueness at the company-account level.
Keep your local key and operation history longer than the provider’s window when you need auditability, but do not assume the provider can still replay an old result. If a delayed job runs after the provider has removed the key, resubmitting it can create a new request. Before allowing long-lived retries, check the operation status through the provider and require a deliberate recovery path when the retention boundary has passed.
Best Value
What idempotency does not solve
- Unsupported endpoints: A provider may support keys for POST but not every action, or may recommend them for POST and PUT only. Verify endpoint-level support.
- External side effects: A payment provider’s replay protection does not automatically deduplicate your email, inventory reservation, ledger write or fulfillment call. Give those systems their own operation IDs and idempotent handling.
- Card or bank state outside the API: A key cannot guarantee what happened in an external network during an outage. Reconcile the provider’s final status and investigate disputes or reversals through its documented workflow.
- Permanent correctness: Finite retention, execution boundaries and transient states mean you should not promise “exactly once” for every payment workflow. Describe the narrower guarantee your endpoint and provider actually document.
Diagnosing duplicate or stuck payments
Two provider payment IDs exist
Check whether your application generated two local operations or rotated the key after a timeout. Compare outbound logs, canonical payloads and worker leases. If two keys were used, idempotency could not identify the second request as a retry; stop further attempts and follow the provider’s refund, cancellation or dispute process.
The same key returns a parameter error
Compare the saved request fingerprint with the retry payload. Common causes are a recalculated tax total, a changed currency representation, a different capture flag or a serializer that omits a field on retry. Restore the original payload for that operation and create a new operation only when the customer intentionally changed the payment.
Retries never resolve
Inspect whether the provider returned a transient signal, whether your backoff is capped, and whether webhook delivery is failing. Query the provider’s status endpoint where available, reconcile by provider payment ID, and move the local operation to a manual-review state rather than issuing unlimited charges.
Free tools Windows power users keep installed
One-click scans. No signup required.
A very old retry creates a new payment
Compare the retry time with the provider’s retention window. A pruned key can lose its deduplication meaning. Require an operator or workflow step to confirm the current payment status before resubmitting operations that outlive the documented window.
Observability and security checklist
- Log the local operation ID, provider, endpoint, key hash or redacted key, attempt number, response status and timing. Avoid logging card data or full authorization headers.
- Alert when one operation receives multiple provider payment IDs, when retries approach their maximum age, or when webhook and API states disagree.
- Make workers acquire a lease or use transactional locking so two processes do not send competing first attempts for the same operation.
- Measure unknown, pending, replayed and permanently failed outcomes separately; a replayed response is not the same as a newly executed payment.
- Rotate credentials and restrict access to stored request data. The idempotency key itself is not a substitute for authentication or authorization.
Key takeaways for an engineering policy
Define an idempotency-key policy per provider and endpoint: key format, maximum length, uniqueness scope, retention window, parameter-mismatch behavior, replay rules and retryable error signals. Make key creation and persistence part of the payment transaction in your own system. On uncertain delivery, retry with the same key and payload, back off, and use webhooks or status queries to establish the final state. Treat retention expiry as a boundary that requires reconciliation, not as permission to submit an old payment again.
For conceptual background, Stripe describes idempotency as “safely retrying requests without accidentally performing the same operation twice” in its engineering article. That protection is powerful when the key is stable and the provider contract is followed, but it is a component of a broader payment workflow rather than a guarantee that every system in the chain executes exactly once.
Quick Recap
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.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems
