All posts

Payments

Your app can charge a user twice for one order

How one idempotency key per payment stops a second tap on Pay, or a retry after a timeout, from charging the user twice.

What to do

  1. Know why a second tap is risky

    The Pay button sends a POST request, and HTTP does not treat a POST as safe to repeat[1]. After a timeout, your app also cannot tell if the first payment went through[1].

  2. Make one random key for each payment

    When the user starts a payment, your app makes one random key for it. Stripe suggests a V4 UUID, and an IETF draft recommends a UUID or a similar random id[1][2].

  3. Send the same key on every try

    A second tap, or a retry after a timeout, sends the same key again. The server uses the key to see that the request is a repeat[2].

  4. Let the key stop the second charge

    Adyen says a payment that is retried with the same key after a timeout gets charged only once[2][3].

  5. Give each new payment its own key

    If you reuse a key with different data, Stripe returns an error[1][2].

The prompt

Paste this into your coding agent before it writes any code.

How to stop double charges
1. When the user starts a payment, make one random key for it.
   A UUID works. Stripe suggests a V4 UUID.

2. Keep that key with the payment until it finishes.

3. Send the key with the payment request, every time.
   A second tap, or a retry after a timeout, sends the same key again.

4. On your server, use the key to spot the repeat,
   so the payment work runs only once.
   If you pay through Stripe or Adyen, send the key to their API too.

5. New payment, new key.
   Never reuse a key with different data.
   Stripe returns an error if you do.

One payment, one key.

Use it when you build or check the payment flow in your app, before real users pay.

Did not fit in the video

The timeout is the hard part. An IETF draft on idempotency keys describes this exact case: the client sent a POST, the request timed out, and the client is left unsure what happened to it[1]. Without a key, a retry is a guess. With a key, the server can see that it already has this request[2].

The two payment providers word their promise in different ways. Adyen says that after a timeout you can retry the same payment call more than once, with a guarantee that the payment is charged only once[2][3]. Stripe says that after a connection error you can repeat the request without the risk of making a second object or doing the update twice[2][3]. Stripe does not use the word "charge" there, so read its promise as "the same request does not run twice".

A UUID is a suggestion, not a rule. Stripe suggests V4 UUIDs or another random string with enough randomness to avoid two keys being the same[1][2]. The IETF text is a draft, not a finished standard, and it only recommends a UUID or something like it[1][2].

When a key comes back with different data, Stripe compares the new request with the first one and returns an error if they do not match[1][2]. The IETF draft suggests the server reply with HTTP status 422 in that case[1][2]. Stripe does not promise that code. No source gives a number for how often double charges happen.

Sources

  1. IETF Internet-Draft draft-ietf-httpapi-idempotency-key-header-08, The Idempotency-Key HTTP Header Field

    datatracker.ietf.org

  2. Stripe API docs, Idempotent requests

    docs.stripe.com

  3. Adyen Docs, API idempotency

    docs.adyen.com

Want the rest? Every post, by month and topic.

See all posts