Glossary6 min readUpdated October 15, 2026

What Is Idempotency, and Why Do Payment APIs Need It?

Idempotency explained: what HTTP says, how idempotency keys work at Stripe, Adyen and PayPal, a $50 retry example, and the Visa duplicate rule.

Nick Bonnassies, CMO at Tagada · checked against 7 sources

Article summary

TL;DR

Idempotency is the property of an operation that has the same effect whether it runs once or many times. In payment APIs, your server sends a unique idempotency key with each charge request. If a timeout forces a retry, the provider sees the same key and returns the first result instead of charging the card again.

HTTP defines PUT, DELETE and the safe methods (GET, HEAD, OPTIONS, TRACE) as idempotent. POST, the method that creates payments, is not.
An idempotency key turns a POST into a safe retry: one key per operation, reused on every retry of that operation.
Stripe keys go up to 255 characters, Adyen keys up to 64, and PayPal recommends UUIDs to fit its 38-character limit.
Each provider only recognizes its own keys. A key sent to one processor does not protect a charge sent to another.
A double charge on the same card, date and amount is a Visa dispute reason (condition 12.6).

Want to go further? Ask

On this page

Idempotency is the property of an operation that gives the same result whether it runs once or ten times. Setting an order status to "shipped" is idempotent: do it twice, the order is still shipped. Charging a card is not: do it twice, the customer pays twice. In payments, idempotency is what lets your server retry a request after a timeout without that risk.

What HTTP says about idempotent methods

The term comes from mathematics, but developers learn it from the HTTP standard. RFC 9110 defines a method as idempotent "if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request."1

Method	Idempotent under RFC 9110	Typical payment use
GET, HEAD, OPTIONS, TRACE	Yes(safe methods)	Read a payment's status
PUT	Yes	Replace a stored object
DELETE	Yes	Remove a saved card or webhook endpoint
POST	No	Create a charge, capture, refund

The standard draws the practical line: "A client SHOULD NOT automatically retry a request with a non-idempotent method unless it has some means to know that the request semantics are actually idempotent."1 Payments run on POST. The idempotency key is that "means to know".

How an idempotency key works

Your server generates a unique key for one operation, sends it with the request, and reuses it on every retry of that same operation. The provider saves the first result under the key. Stripe saves "the status code and body of the first request" and returns it on retries, "including 500 errors."3 Here is a request based on Stripe's API reference, with illustrative values:

curl https://api.stripe.com/v1/payment_intents \
  -u "sk_test_...:" \
  -H "Idempotency-Key: 5b8f2c1e-6a3d-4f7e-9c21-0d4e8a7b3f10" \
  -d amount=5000 \
  -d currency=usd \
  -d payment_method=pm_card_visa \
  -d confirm=true

5000 is in cents, so $50.00. Stripe accepts keys on every POST and says sending them on GET or DELETE "has no effect".3

The header has no single standard. The IETF wrote one, "The Idempotency-Key HTTP Header Field", but its latest version (draft-ietf-httpapi-idempotency-key-header-07, October 15, 2025) is an expired Internet-Draft, not an RFC.2 Providers set their own rules:

	Stripe	Adyen	PayPal
Header	`Idempotency-Key`	`idempotency-key`	`PayPal-Request-Id`
Max length	255 characters	64 characters	38 (UUID recommended)
How long it lasts	Can be removed after 24 hours	7 to 14 days	Set per API
What a retry returns	The first saved response	The first response	The latest status of the request

Sources: Stripe, Adyen and PayPal docs, read October 14, 2026.3 4 5 The basics also appear in our payment API entry; this page explains why they matter.

Example: a timeout during a $50 charge

Shopper pays. Your server creates a key for this order's charge and stores it with the order before calling the provider.
Charge sent. The provider approves $50 and saves the response under the key.
Response lost. Your server only sees a timeout. It can't tell whether the card was charged.
Same request, same key. Your server retries with the identical body and key.
One charge. The provider recognizes the key and returns the saved approval, with the same payment ID. The customer pays $50, not $100.

Illustrative example. Without the key, step 4 would create a second $50 charge.

Two edge cases come from the docs. If the first request is still running when the retry arrives, Adyen returns HTTP 422 or 409 with error 704, "request already processed or in progress".4 And a decline is a result too: Primer says a declined payment "is still considered Successfully processed", so retrying it needs a new key.7

Idempotency vs retries vs deduplication

	Idempotency	Retry	Deduplication
What it is	A guarantee: repeating has no extra effect	An action: sending the request again	A technique: spotting a repeat by its ID
Who does it	The provider, using your key	Your server	Whoever receives the message
Payment example	Same key returns the first charge	Resend after a timeout	Skip a webhook event ID you've seen
Risk without it	Retries create double charges	Payments lost on a network blip	Orders shipped twice

Retries are only safe on top of idempotency. Deduplication is how you make your side idempotent, for example on webhooks, which providers can deliver more than once.

Why merchants care: the Visa duplicate rule

A double charge is not just a refund to issue. Visa lets the issuer open a dispute under condition 12.6, Duplicate Processing, when "a single Transaction was processed more than once using the same Payment Credential on the same Transaction date, and for the same Transaction amount." The issuer has 120 days from the processing date and certifies the acquirer reference number of the valid charge.6

The rule also covers charges split across acquirers: if the issuer can't tell which one is invalid, "the Acquirer that processed the second Transaction is responsible for the Dispute."6 That matters when you route between processors. An idempotency key only protects calls to the provider that stored it, and Adyen notes its keys are not even checked across its own regional endpoints.4 After a timeout, confirm the outcome with the first processor before sending the payment to a second one. A retry after a clear decline is a different case, with its own Visa limits: see hard decline and cascading payments.

How Tagada helps

One payment logic across processors

Tagada follows Visa and Mastercard rules and the laws that apply to payments. Payments route across Stripe, Adyen and our own TagadaPay processor with one logic, with a cascade on decline.

For the full integration walkthrough, see how to integrate a payment gateway; for routing between processors, dynamic payment routing.

Updated on October 15, 2026

Nick Bonnassies

CMO at Tagada

CMO at Tagada. Before Tagada, Nick built direct-to-consumer brands that generated over $115M in sales, raised over $25M in crowdfunding and sold two of them. He also works as a fractional CMO on marketing operations and AI systems.

Frequently asked questions

What is an idempotency key?

It's a unique string your server attaches to an API request, usually in an Idempotency-Key header. The provider stores the first result under that key. If the same request arrives again with the same key, it returns that stored result instead of running the operation a second time. Stripe and Adyen both suggest a random V4 UUID.

Is POST idempotent?

No. RFC 9110 lists PUT, DELETE and the safe methods (GET, HEAD, OPTIONS, TRACE) as idempotent. POST is not on the list, and a client should not retry it automatically unless it knows the request is safe to repeat. That is why payment APIs, which create charges with POST, add idempotency keys.

How long does an idempotency key last?

It depends on the provider. Stripe can remove a key once it is at least 24 hours old, and a reused key after that creates a new request. Adyen keys are valid 7 to 14 days after first submission. PayPal stores its request ID for a period set by each API. Retry inside that window.

What happens if I reuse a key with different parameters?

Stripe compares the new parameters with the original request and returns an error if they differ. The IETF draft suggests an HTTP 422 for this case and a 409 when the first request is still being processed. Treat it as a bug in your code, not a reason to retry.

Should I retry a declined payment with the same key?

No. A decline is a final answer to that request, and the provider will just replay it. Primer says a declined payment still counts as successfully processed, so a new attempt needs a new key. Check the decline code first: some declines must never be retried.

Is idempotency the same as deduplication?

Not quite. Idempotency is the guarantee that repeating an operation changes nothing more. Deduplication is one way to get it: spotting a repeat by its ID and skipping it. Your webhook handler deduplicates events by ID so that handling the same event twice is idempotent.

Sources

Checked October 15, 2026

Tagada

One checkout, several processors behind it

Funnels, one-click upsells, subscription billing and payment routing, on one customer record.

Start free See pricing

01Create your free account
02Connect your store or build a checkout
03Launch funnels, upsells and subscriptions