Why You Should Never Use a Random UUID as an Idempotency Key in Payment APIs

Imagine you have a saas and your user clicks "Pay", but the network times out, so they hit the button again.

Your backend processes the same request twice.

💥 Result? Two charges. Angry user. Support ticket. Refund dance.

Recently, I started building a personal project using a monolithic architecture and integrated Stripe for billing. As expected, YouTube began recommending all sorts of payment integration videos.

One of them caught my attention — and nearly made me choke on my dinner.

In the video, the creator was integrating with Mercado Pago and explained the use of the X-Idempotency-Key header by saying:

"Just use randomUUID() from Node here. It just needs to be unique."

Seems harmless, right? But that one line can break the whole concept of idempotency especially in payment systems.

---

🧠 What Is Idempotency, Really?

Idempotency ensures that multiple identical requests only have one effect.

If the first request goes through and the second one is retried — whether due to a flaky network, user impatience, or frontend retry logic — the backend should return the same result, not perform the operation again.

✅ Example:

1. User tries to subscribe to your service.
2. You send a request to Mercado Pago → an invoice is created.
3. User refreshes the page and submits again.
4. If the request includes the same idempotency key, the same invoice is returned — no duplicate charge.

That’s the power of headers like:

X-Idempotency-Key: invoice-1234-user-5678

---

❌ The Problem with UUID.randomUUID()

If you generate a new UUID for each retry, the server can't detect that it's the same operation.

Each request looks completely unique.

So instead of being safe and idempotent, you get:

• ❌ First request → Charge created
• ❌ Second request → Another charge created
• 💣 Third request → Yep... you get the idea

---

✅ What You Should Do Instead

An idempotency key must be deterministic:

the same operation should always produce the same key.

You can use:

• A combination of userId + invoiceId
• A traceId or sessionId from the frontend
• A fingerprint of the payload (e.g. hash of the JSON body)

Examples:

const key = "invoice-" + userId + "-" + invoiceId;

or something like

const key = sha256(JSON.stringify({
  userId: "1234",
  plan: "pro",
  price: "49.90"
}));

This ensures idempotency across retries, across network hops, even across frontend reloads.

---

🛡️ Backend Handling

On the server side, the logic is straightforward:

Receive the X-Idempotency-Key header

Check if that key already exists in storage

If yes → return the saved response

If no → process, store the response + key

Storage options:
Relational DB with unique constraint on the key

Redis with TTL

Distributed cache or NoSQL with atomic writes

Bonus tip: log the idempotency key with your trace logs to simplify debugging.

💡 Real-World Examples: Stripe & Mercado Pago

Both Stripe and Mercado Pago rely heavily on idempotency keys to avoid duplicate charges.

Their APIs require that you set this key once per operation, and they cache the result server-side.

If you change the key on each retry — like using a UUID.randomUUID() — you lose all protection.

🧵 Pro Tip: Where to Generate the Key?

Ideally, the client(frontend, api caller) should generate the key once per operation and persist it until it's confirmed successful.

If you use traceId or a sessionId, make sure it persists across retries (not regenerated).

On mobile apps, you can store it in local storage or memory.

The important thing is: same intent → same key.

📌 Final Thoughts

Idempotency isn't about "not crashing on retry" —
it's about not duplicating irreversible effects.

Random UUIDs are great for correlation IDs or primary keys —
but not for identifying business operations.

So next time you're building a billing integration or an API that creates side effects, ask yourself:

“What happens if this request is sent twice?”

And remember:

🧨 Random UUIDs ≠ Idempotency

💬 Have you ever seen this bug happen in production?

Or used UUID.randomUUID() without thinking twice?

Drop a comment below — let’s share some war stories 😅