Idempotency Keys: How to Prevent Double Charges

An idempotency key is a unique value your system sends with a payment request so that a repeat of the same request is recognised as the same attempt. If a customer taps pay twice, or your server retries after a timeout, the provider sees the same key and does not create a second charge. One key per payment attempt means one charge, however many times the request is sent.

• Idempotent: doing the same thing again has the same result as doing it once.
• Idempotency key: a unique value that identifies one payment attempt.
• Why it matters: repeated requests are common, and without a safeguard each could become a new charge.

This guide is the written companion to our short video on the same topic.

What is an idempotency key?

An idempotency key is a unique string that your system generates for each payment attempt and sends with the request. The provider remembers the key together with the result. If the same key arrives again, the provider returns the earlier result instead of doing the work again.

The word idempotent comes from mathematics. It means that repeating an action leaves the result unchanged after the first time.

Why do duplicate payment requests happen?

Repeated requests are normal on the internet, even when nobody intends them.

• A customer taps the pay button twice, or taps again because nothing seemed to happen.
• A network connection drops, and the browser or app sends the request again.
• Your own server times out waiting for an answer and retries.
• A queue or job system runs the same task twice.

In each case your system cannot be sure whether the first request succeeded. Without a safeguard, the safe-looking choice, trying again, can become a second charge. A related problem on the receiving side is covered in our guide to payment webhooks, where the same message can also arrive twice.

How does an idempotency key prevent a double charge?

Suppose a customer taps pay twice, and two requests leave your checkout. Both carry the same key because both belong to the same attempt. The provider processes the first one and stores the result against the key. When the second arrives, the provider sees the key, does not charge again, and returns the stored result.

The customer is charged once, and your system receives a clear answer for both requests. To see where this sits in the full path of a payment, read how a card payment moves.

How should you create and use a key?

Good practice is simple, but the details are set by each provider, so follow your provider's documentation.

• One key per attempt. Generate a new unique key for each new payment attempt, and reuse the same key only when you retry that same attempt.
• Use unpredictable values. A random identifier is a common choice.
• Keep the key with the order. Store it so a retry after a failure can send the same one.
• Know how long keys last. Providers keep keys for a limited time, and the length varies.

A new attempt, for example a customer retrying after a decline, should get a new key. See why a card payment gets declined for how to tell a retry from a new attempt.

What should you test?

Test double submission before launch: send the same request twice and confirm that only one payment exists. Also test a timeout followed by a retry. Our payment integration testing checklist lists the failure cases worth covering.

FAQ

What is an idempotency key in simple words?

It is a unique value sent with a payment request, so that if the same request is sent again, the system recognises it as the same attempt and does not charge twice.

Does an idempotency key stop a customer paying twice on purpose?

No. Two separate attempts have two separate keys. The key only protects against the same attempt being sent more than once.

Who creates the key, my system or the provider?

Usually your system creates it and sends it with the request. Check your provider's documentation for the exact header or field name.

How long does a provider remember a key?

That depends on the provider. Check the documentation rather than assuming a standard period.

Is a retry after a decline a new attempt?

Usually yes, because the first attempt has its own result. Use a new key for a new attempt, and the same key only for repeats of the same one.