Idempotency Keys (Preventing Duplicate Charges)

In distributed systems, networks are inherently unreliable. A client might send a request to a server, but the network connection drops or times out before the client receives the server's response.

If that original request was a "Charge $50" command, the client doesn't know if the charge actually succeeded or failed. Out of panic, they click the "Pay" button again. This can easily lead to a disastrous Duplicate Charge.

To solve this, system designers implement Idempotency. An operation is "idempotent" if running it one single time has the exact same effect as running it 1,000 times.

---

1. How Idempotency Keys Work

When a client wants to perform a highly sensitive, mutating action (like processing a payment or creating an order), the client (Web/Mobile App) generates a uniquely random string called an Idempotency Key (usually a standard UUID). It sends this key locked inside the HTTP Header of the request.

The server checks if it has ever seen this exact Idempotency Key recently:

• First time seeing it? The server happily processes the payment, saves the result to a database, and remembers the key.
• Seen it before? The server safely assumes this is a desperate "retry" from the client. It completely skips the payment logic and simply identically returns the cached success response from the first attempt.

---

2. Architecture Diagram

---

3. High-Level Architecture Code Example

Here is a highly readable Node.js / Express example showing exactly how to implement Idempotency logic using Redis as our blazing-fast key-storage mechanism.

const express = require("express");
const redis = require("redis");
const stripe = require("./fake-stripe-api"); // Fake payment processor

const app = express();
app.use(express.json());

// Connect to an incredibly fast in-memory store to check keys rapidly
const cache = redis.createClient({ url: "redis://my-redis" });
// await cache.connect(); // (Assumed connected in this example)

app.post("/api/payments/charge", async (req, res) => {
  const { amount, userId } = req.body;

  // 1. EXTRACT THE KEY: The client MUST send this in the headers
  const idempotencyKey = req.headers["x-idempotency-key"];

  if (!idempotencyKey) {
    return res
      .status(400)
      .json({ error: "Idempotency-Key header is absolutely required" });
  }

  try {
    // 2. CHECK CACHE: Have we seen this exact key in the last 24 hours?
    const cachedResponse = await cache.get(`idempotency_key:${idempotencyKey}`);

    if (cachedResponse) {
      // 🔥 MAGIC: We have seen this key! Do NOT charge the user again.
      // Just return the exact same response we gave them the first time.
      console.log("Duplicate request prevented! Returning cached response.");
      return res.status(200).json(JSON.parse(cachedResponse));
    }

    // 3. PROCESS PAYMENT: This is the first time we've seen the key.
    // We physically execute the heavy, sensitive logic.
    console.log(`Processing new $${amount} charge for User ${userId}...`);
    const paymentResult = await stripe.chargeUser(userId, amount);

    // Prepare our API's final answer
    const serverResponse = {
      success: true,
      transactionId: paymentResult.id,
      message: "Payment successfully processed",
    };

    // 4. SAVE THE KEY: Store the response in Redis tied to this specific key.
    // We set it to forcefully expire in 24 hours (86400 seconds) to save disk space.
    await cache.setEx(
      `idempotency_key:${idempotencyKey}`,
      86400,
      JSON.stringify(serverResponse)
    );

    // 5. RESPOND: Send success to the client
    return res.status(200).json(serverResponse);
  } catch (error) {
    console.error("System Error", error);
    return res.status(500).json({ error: "Internal Server Error" });
  }
});

app.listen(8080, () => console.log("Idempotent Payment API running..."));

---

4. Key Takeaways

1. The Client is Responsible: The front-end mobile app or website MUST generate the UUID and painstakingly hold onto it when they hit "Retry". If they accidentally generate a new UUID when they hit retry, they will instantly be double-charged.
2. Short Lifespans: You don't need to store idempotency keys forever. Once a user successfully sees the "Payment Success" screen, the exact key is virtually useless. Throwing the keys away after 24-48 hours saves massive amounts of expensive database storage.
3. Atomic Locks (Advanced): In systems under extreme, heavy load, you might get two geographically identical requests at the exact same millisecond before Redis has time to save the first result. In those extreme cases, engineers use Distributed Locks (like Redis Redlock) to ensure absolutely only one single process can even read or write the key at a time.