Idempotency Keys: The Secret to No Double Charges in Payment APIs

Ever had your connection stall right as you hit Pay, then panic-clicked three times? If the endpoint is not idempotent, the balance can be cut more than once. Meet the idempotency key.

Read in Indonesian

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-Key header carries a unique UUID per transaction, and works like a parking ticket: used once, then only replayed.
  • Redis with SET NX EX is 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/orders three 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:

  1. Check the key in Redis first. The backend asks whether the key idempotency:a1b2-c3d4-e5f6 already exists.
  2. 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.
  3. The key is currently being processed. If another request with the same key arrives while the first is still running, the server replies 409 Conflict at once: "Transaction in progress, please wait a moment!". This is what prevents a race condition.
  4. 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: true header.

A Simple Implementation in FastAPI

Here is a simple guard in FastAPI that leans on Redis:

PYTHON
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:

  1. 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.
  2. 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.
  3. 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. 👋

Inva

Writer

Get better at shipping code.

Join the other developers getting tech updates, tips, and relaxed tutorials in their inbox every week.

Stay in the loop

Tech updates, coding tips, and relaxed insights straight to your inbox every week.

No spam. Unsubscribe anytime.

Read next

See all

For developers who learn by struggling

© 2026 Inva.dev.