Have you ever been paying a bill in a shopping app, and the connection stalled right as you pressed "Pay Now"? The screen shows only a loading spinner with no answer, so you panic and tap the button three more times in a row.
A few seconds later an SMS arrives: your account balance was cut four times for one single order. 😱
In backend engineering, this financial nightmare is called Double Charge. The main cause is a network failure: the request did reach the server and was processed, but the success response never made it back to the app. The app retries, and the server executes again.
To keep transactions safe on a flaky network, financial systems rely on a mechanism called the Idempotency Key.
Key takeaways
- An idempotent operation leaves the system in the same final state whether you run it once or many times, with no extra side effects.
- POST is not idempotent by default, so a payment endpoint is prone to double charges when a request is retried.
- The
Idempotency-Keyheader carries a unique UUID per transaction, and works like a parking ticket: used once, then only replayed. - Redis with
SET NX EXis a fast guard that locks a request in progress, and the original response is stored so it can be replayed.
What Does Idempotent Actually Mean?
In mathematics and computer science, an operation is idempotent when running it once or many times produces exactly the same final system state, with no additional side effects.
In the HTTP protocol, this property is attached to several methods:
- GET: idempotent. Fetching a user profile 10 times will not change the balance or any data.
- DELETE: idempotent. Deleting the post with ID 42 once or five times gives the same result: the post is gone from the system.
- POST: not idempotent. Calling
POST /api/ordersthree times creates three new orders and cuts the balance three times.
So the challenge is clear: how do you make a POST endpoint behave idempotently when it is retried?
The Fix: The Idempotency-Key Header
The industry standard, see the Stripe Idempotency API and the IETF Idempotency-Key Header draft, requires the client to send a unique header named Idempotency-Key on every critical transaction request. That header is usually a random UUIDv4 string.
To picture it, think of the automated parking machine in a building. The machine prints one ticket with a unique barcode, for example TRX-9988. When you leave and tap that ticket, you pay Rp10,000. If you idly tap the same TRX-9988 ticket a minute later, the machine will not charge another Rp10,000. It just shows the status "This ticket was already paid at 14.05. The gate is open!"
That ticket barcode is the analogy for the Idempotency Key.
How It Works Behind the Scenes
When a request arrives at the backend carrying Idempotency-Key: a1b2-c3d4-e5f6, the backend runs this protection flow:
- Check the key in Redis first. The backend asks whether the key
idempotency:a1b2-c3d4-e5f6already exists. - New key, never seen before. The backend sets an atomic lock with
SET key "PROCESSING" NX EX 120, executes the payment, then stores the status and JSON response payload in Redis with a lifetime, say 24 hours. - The key is currently being processed. If another request with the same key arrives while the first is still running, the server replies
409 Conflictat once: "Transaction in progress, please wait a moment!". This is what prevents a race condition. - The key already succeeded. The server does not re-run the balance cut or the payment gateway. The old response is read from Redis and sent back as a cached response replay, with an extra
Idempotent-Replayed: trueheader.
A Simple Implementation in FastAPI
Here is a simple guard in FastAPI that leans on Redis:
import json
import redis.asyncio as aioredis
from fastapi import FastAPI, Header, HTTPException, status
from pydantic import BaseModel
app = FastAPI()
r = aioredis.from_url("redis://localhost:6379", decode_responses=True)
class PaymentRequest(BaseModel):
account_id: str
amount: float
@app.post("/api/charge")
async def process_payment(
payload: PaymentRequest,
idempotency_key: str = Header(..., description="UUID unik untuk transaksi ini")
):
cache_key = f"idempotency:{idempotency_key}"
# 1. Check whether this transaction already completed before
cached_data = await r.get(cache_key)
if cached_data:
record = json.loads(cached_data)
if record.get("status") == "PROCESSING":
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Transaksi dengan kunci ini sedang diproses. Mohon tunggu."
)
# Replay the old response, without cutting the balance again!
return record.get("response")
# 2. Set the atomic lock (SET NX EX) for 60 seconds
acquired = await r.set(
cache_key,
json.dumps({"status": "PROCESSING"}),
nx=True,
ex=60
)
if not acquired:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Permintaan bersamaan terdeteksi."
)
try:
# 3. Execute the actual business transaction (simulated balance cut)
# call_payment_gateway(payload.account_id, payload.amount)
result = {
"status": "success",
"message": f"Berhasil memotong saldo Rp{payload.amount:,.0f}",
"transaction_id": f"TRX-{idempotency_key[:8]}"
}
# 4. Store the success response in Redis (TTL 24 hours = 86400 seconds)
await r.set(
cache_key,
json.dumps({"status": "COMPLETED", "response": result}),
ex=86400
)
return result
except Exception:
# On an unexpected technical error, drop the lock so the user can retry
await r.delete(cache_key)
raise HTTPException(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail="Gagal memproses pembayaran. Silakan coba lagi."
)
Three Things People Miss
To make your Idempotency Key implementation genuinely sturdy, there are three things often missed:
- Combine the key with the user ID. Use the pattern
idempotency:user_123:key_abc, not the bare key. Otherwise a curious user can guess someone else's key. - Match the request body. Compute a SHA-256 hash of the payload. If a request with the same key carries a different amount, reject it with
422 Unprocessable Entity. This blocks data tampering. - Pick a sensible TTL. Keep the key in Redis for 24 to 72 hours. After that period, treat it as expired.
One More Thing: Redis Is Not the Only Guard
An important point that often gets missed: Redis is fast, but it is not always the source of truth. If your Redis dies or gets flushed, every idempotency key is gone, and a retried request slips through as a new transaction.
For a genuinely critical payment system, also keep the idempotency record in your transaction database, with a unique idempotency_key column. Redis gives you a fast check on the hot path, the database gives you the long-term guarantee. Both run together.
Handling a flaky network and impatient users is a fundamental architectural responsibility. With an Idempotency Key on every critical endpoint, your payment system becomes immune to duplicate transactions and friendly to auto-retry.
Happy coding, and may your users' money never get cut twice. 👋