Idempotency Keys: What Most Tutorials Don't Tell You

Every payment flow has a silent enemy: the network. Requests time out, connections drop, users panic, and click twice. What happens to your system when the same charge arrives more than once?
I used to think idempotency keys were one of those "nice-to-have backend things."
You know the kind you tell yourself you'll fix later. That thinking is dangerous.
When it comes to payments, idempotency isn't a feature; it's what prevents duplicate charges and inconsistent state.

The Problem: "The Double Tap"

Imagine this:

1. A user clicks "Pay"
2. The network is slow, or their Wi-Fi drops
3. They click "Pay" again
4. Your API receives two identical requests

If you're not handling this correctly:

• The user gets charged twice
• Your database ends up in a weird state
• You lose user trust instantly

This doesn't require a bug. It's normal behavior in distributed systems.

What Is Idempotency?

In simple terms:

You can send the same request multiple times, but it will be processed only once.

Every retry with the same key should return the same result as the first successful request.

Important edge case: idempotency ≠ caching

It's tempting to think:

"If something fails, just return the same failure."

But it's not that simple.

• If the request never reached your server logic, a retry should proceed normally
• If the request may have started processing, you must rely on stored state, not assumptions
• If an external system (like a payment provider) already processed the charge, a retry must not trigger it again

Idempotency protects against duplicate processing, not against retrying genuinely unprocessed requests.

The Key: Idempotency-Key

To make this work, every payment intent needs a unique identifier.
This key must be generated once per intent (not per click) and reused across retries.

// ❌ WRONG: New key on every click
// const handlePay = () => {
//   const key = crypto.randomUUID();
// }

// ✅ RIGHT: One key per payment intent
const idempotencyKey = crypto.randomUUID(); // generate when checkout loads

fetch('/api/payments/charge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey
  },
  body: JSON.stringify(payload)
});

Where does the key live on the client?

"Generated once" means you need to persist it across retries.
Good options:

• React state or a ref (single-page flow)
• sessionStorage (if reloads are possible)
• A server-generated key passed into the checkout session

The key should be tied to the intent, not the button click.

🔒 Security note: Idempotency keys can reveal payment patterns (e.g., same key on retry = something went wrong). Always send them over HTTPS, and avoid logging full keys in plaintext in production logs; hash or truncate if needed.

The Server Side: Where the Real Work Happens

Sending the header does nothing unless your backend actually uses it.
Here's the core logic:

async function handleChargeRequest(req, res) {
  const key = req.headers['idempotency-key'];

  if (!key) {
    return res.status(400).json({ error: 'Idempotency-Key header is required' });
  }
  const existing = await keyStore.get(key);

  // 🚨 Same key must always mean the same intent
  if (existing) {
    const currentSignature = extractBusinessSignature(req.body);
    const storedSignature = existing.businessSignature;

    if (currentSignature !== storedSignature) {
      return res.status(409).json({
        error: 'Idempotency key reused with different payment details'
      });
    }
    return res.status(existing.statusCode).json(existing.body);
  }

  // Process the payment
  const result = await paymentProvider.charge(req.body);
  const statusCode = result.success ? 200 : 400;

  // Store every deterministic response (success or known failure)
  await keyStore.set(key, {
    statusCode,
    body: result,
    businessSignature: extractBusinessSignature(req.body)
  });
  return res.status(statusCode).json(result);
}

// Only include immutable business fields - never timestamps, request IDs, or metadata
function extractBusinessSignature(payload) {
  return JSON.stringify({
    amount: payload.amount,
    currency: payload.currency,
    customerId: payload.customerId,
  });
}

If the payment provider returns a failure (e.g., 402 or 500), you should store that response just like a success. Otherwise, a retry might reprocess the same key and produce a different result, breaking idempotency.

The only exception is when the result is unknown (e.g., network timeout or provider unavailable). In those cases, the client should retry with the same key, and your system should check the provider state before deciding what to return.

The Real Danger: Concurrency

Here's where most implementations break.
Two identical requests can arrive at the same time:

• both check "key not found"
• both proceed
• both charge the user

Game over.

The fix

You need a database-level unique constraint on the idempotency key.
This is what actually makes sure only one request wins.

CREATE TABLE idempotency_keys (
  key TEXT PRIMARY KEY,
  response JSONB,
  status_code INT,
  business_signature TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

In production, the key should be inserted with a unique constraint before processing the payment to avoid race conditions.

If two requests try to insert the same key:

• one succeeds
• the other fails → and must fetch the stored result

Without this, your idempotency is not reliable.

Don't use SQL?

The unique constraint is ideal, but here are alternatives:

• Redis: SET key value NX EX ttl (atomic create-if-not-exists)
• MongoDB: unique index on idempotencyKey
• DynamoDB: conditional write with attribute_not_exists(idempotencyKey)

Whatever you use, the operation must be atomic. A check-then-insert pattern will always have a race condition.

Fake Idempotency (Very Common)

A lot of systems look correct, but aren't.
Examples:

• checking the key but not storing the response
• storing the key but not handling concurrency
• using in-memory storage in a distributed system

This creates a false sense of safety, which is worse than having none.

Key Expiration: The Gotcha Nobody Mentions

Idempotency keys shouldn't live forever.
A typical approach:

• keep them for ~24 hours
• clean up old entries

Why?

• prevents unlimited storage growth
• gives you a safe retry window

After expiration, the same key can be treated as new. This is fine only if the original session has ended (for example, the user abandoned checkout).

⚠️ Be careful: if a key expires while a payment is still processing (rare, but possible), a retry could create a duplicate. Set expiration long enough to cover your processing time and retry window. 24 hours is usually safe for most payment flows.

The Full Flow

CHECKOUT LOADS
      ↓
Generate idempotency key (once)
      ↓
User clicks "Pay"
      ↓
POST /charge (Idempotency-Key)
      ↓
SERVER: Key exists? ── YES → return stored response ✓
      │
      NO
      ↓
Try to insert key (unique constraint)
      │
      ├─ success → process payment → store result
      │
      └─ fail → fetch existing result
      ↓
Return response

A Quick Note on HTTP Methods

GET requests are intended to be idempotent; calling them multiple times should not change server state.
Idempotency keys are mainly for POST and PATCH - basically, anything that changes state.

Idempotency Beyond Payments

This isn't just about payments. The same idea applies to:

• email sending (avoid duplicates)
• webhook handling (providers retry delivery)
• message queues (at-least-once delivery)
• database writes (deduplication)

Anywhere you need exactly-once behavior on unreliable networks, idempotency is your tool.

How to Test It (Because Trust, But Verify)

💡 Pro tip: Don't just hope it works, prove it.
In your tests, send the same idempotency key twice:

test('idempotent charge: second request returns cached result', async () => {
  const key = 'test_order_123';
  const payload = { amount: 2000, currency: 'USD', customerId: 'cus_abc' };

  // First request — processes payment
  const res1 = await request(app).post('/charge')
    .set('Idempotency-Key', key)
    .send(payload);

  // Second request — should return cached result, NOT call payment provider again
  const res2 = await request(app).post('/charge')
    .set('Idempotency-Key', key)
    .send(payload);
  expect(res2.body).toEqual(res1.body);
  expect(paymentProviderMock.charge).toHaveBeenCalledTimes(1); // 🔑 critical check
});

If your mock gets called twice, your idempotency is leaking. Fix it before prod.

Quick Checklist

Before shipping a payment flow:

• [ ] Key generated once per intent
• [ ] Key persisted across retries
• [ ] Backend checks key before processing
• [ ] Response is stored and reused
• [ ] Payload consistency is validated
• [ ] Database enforces a unique constraint
• [ ] Key store is shared across instances
• [ ] Expiration policy is defined

If one of these is missing, it's not done.

---

TL;DR

Client sends the same key. The server enforces a unique constraint. Store every result (success or failure). Return stored result on retry.
Miss any of these? You don't have idempotency. You have hope.
The double tap is coming. Be ready for it.