Stop Charging Customers Twice - Idempotency Keys in Express for Beginners

 Customer Our Checkout API Fake Provider | | | |-- POST /pay ---->| | | |-- POST /v1/charges ------->| charges card 💸 | | Idempotency-Key: K1 | ...answer is slow 🐢 | | (times out after 1s) | | | | | |-- retry, SAME key K1 ----->| "seen K1 before" | |<-- 201 (replayed) ---------| no new charge ✅ |<-- paid ---------| | 

mkdir idempotency-keys-demo && cd idempotency-keys-demo npm init -y npm install express@5 npm install -D typescript @types/express @types/node@22 npm pkg set type=module scripts.build="tsc" scripts.start="node dist/server.js" 

idempotency-keys-demo/ ├── src/ │ ├── fakeProvider.ts │ ├── paymentClient.ts │ ├── orders.ts │ ├── app.ts │ └── server.ts ├── demo.sh ├── tsconfig.json └── package.json 

{ "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "outDir": "dist", "rootDir": "src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "types": ["node"] }, "include": ["src"] } 

import express from "express"; import { createHash, randomUUID } from "node:crypto"; // A tiny pretend payment provider. NOT Stripe, NOT Paystack. // It only copies the idea: same Idempotency-Key + same body = same answer. type Charge = { id: string; orderId: string; amount: number; currency: string }; type SavedResult = { bodyHash: string; status: number; body: unknown }; const charges: Charge[] = []; const idempotencyStore = new Map<string, SavedResult>(); let slowResponsesLeft = 0; const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); const hashBody = (body: unknown) => createHash("sha256").update(JSON.stringify(body)).digest("hex"); export const provider = express(); provider.use(express.json()); provider.post("/v1/charges", async (req, res) => { const key = req.get("Idempotency-Key"); const bodyHash = hashBody(req.body); if (key) { const saved = idempotencyStore.get(key); if (saved && saved.bodyHash !== bodyHash) { res.status(422).json({ error: "Idempotency-Key was already used with a different body" }); return; } if (saved) { res.set("Idempotent-Replayed", "true").status(saved.status).json(saved.body); return; } } const { orderId, amount, currency } = req.body as Omit<Charge, "id">; const charge: Charge = { id: `ch_${randomUUID().slice(0, 8)}`, orderId, amount, currency }; charges.push(charge); // 💸 money has moved if (key) idempotencyStore.set(key, { bodyHash, status: 201, body: charge }); if (slowResponsesLeft > 0) { slowResponsesLeft--; await sleep(3000); // the "network is bad" part: charged, but the answer is late } res.status(201).json(charge); }); // Test helpers so we can see what happened provider.get("/v1/charges", (_req, res) => { res.json({ count: charges.length, charges }); }); provider.post("/__test/slow", (req, res) => { slowResponsesLeft = Number(req.query.times ?? 1); res.json({ slowResponsesLeft }); }); 

const PROVIDER_URL = process.env.PROVIDER_URL ?? "http://localhost:4000"; const TIMEOUT_MS = 1000; const MAX_ATTEMPTS = 3; export type ChargeParams = { orderId: string; amount: number; currency: string }; export type Charge = ChargeParams & { id: string }; const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); // Errors worth retrying: timeouts, network drops, "busy", "slow down", server errors const isRetryableStatus = (status: number) => status === 409 || status === 429 || status >= 500; export async function createCharge( params: ChargeParams, getKey: () => string // where the Idempotency-Key comes from ): Promise<Charge> { let lastError: unknown; for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) { const key = getKey(); try { const res = await fetch(`${PROVIDER_URL}/v1/charges`, { method: "POST", headers: { "Content-Type": "application/json", "Idempotency-Key": key }, body: JSON.stringify(params), signal: AbortSignal.timeout(TIMEOUT_MS), }); if (res.ok) { const replayed = res.headers.get("Idempotent-Replayed") === "true"; console.log(`attempt ${attempt} key=${key.slice(0, 8)} -> ${res.status}${replayed ? " (replayed)" : ""}`); return (await res.json()) as Charge; } if (!isRetryableStatus(res.status)) { throw new Error(`Provider said no: ${res.status} ${await res.text()}`); } lastError = new Error(`Provider returned ${res.status}`); } catch (err) { if (err instanceof Error && err.message.startsWith("Provider said no")) throw err; lastError = err; console.log(`attempt ${attempt} key=${key.slice(0, 8)} -> ${(err as Error).name}`); } await sleep(200 * 2 ** attempt); // 400ms, 800ms, ... } throw lastError; } 

import { randomUUID } from "node:crypto"; export type Order = { id: string; amount: number; // minor units, e.g. kobo currency: string; status: "pending" | "paid"; paymentKey: string; // the Idempotency-Key for paying THIS order chargeId?: string; }; // In-memory "database". In real life this is a table with a unique paymentKey column. const orders = new Map<string, Order>(); export function createOrder(amount: number, currency: string): Order { const order: Order = { id: `ord_${randomUUID().slice(0, 8)}`, amount, currency, status: "pending", paymentKey: randomUUID(), // created and saved BEFORE any payment attempt }; orders.set(order.id, order); return order; } export const findOrder = (id: string) => orders.get(id); export function markPaid(order: Order, chargeId: string) { order.status = "paid"; order.chargeId = chargeId; } 

import express from "express"; import { randomUUID } from "node:crypto"; import { createCharge } from "./paymentClient.js"; import { createOrder, findOrder, markPaid } from "./orders.js"; export const app = express(); app.use(express.json()); app.post("/orders", (req, res) => { const { amount, currency } = req.body as { amount: number; currency: string }; if (!Number.isInteger(amount) || amount <= 0 || typeof currency !== "string") { res.status(400).json({ error: "amount (integer, minor units) and currency are required" }); return; } res.status(201).json(createOrder(amount, currency)); }); // ❌ The bug: a brand-new key on every attempt app.post("/orders/:id/pay-naive", async (req, res) => { const order = findOrder(req.params.id); if (!order) { res.status(404).json({ error: "Order not found" }); return; } const charge = await createCharge( { orderId: order.id, amount: order.amount, currency: order.currency }, () => randomUUID() ); markPaid(order, charge.id); res.json(order); }); // ✅ The fix: one key per order, saved before the first attempt, reused every time app.post("/orders/:id/pay", async (req, res) => { const order = findOrder(req.params.id); if (!order) { res.status(404).json({ error: "Order not found" }); return; } if (order.status === "paid") { res.json(order); // already paid, nothing to do return; } const charge = await createCharge( { orderId: order.id, amount: order.amount, currency: order.currency }, () => order.paymentKey ); markPaid(order, charge.id); res.json(order); }); app.get("/orders/:id", (req, res) => { const order = findOrder(req.params.id); if (!order) { res.status(404).json({ error: "Order not found" }); return; } res.json(order); }); app.use((err: Error, _req: express.Request, res: express.Response, _next: express.NextFunction) => { console.error(err); res.status(502).json({ error: "Payment status unknown. Do not charge again; check with the provider." }); }); 

import { app } from "./app.js"; import { provider } from "./fakeProvider.js"; provider.listen(4000, () => console.Source：https://dev.to/fredabod/stop-charging-customers-twice-idempotency-keys-in-express-for-beginners-10gp
My favorites