Saltar al contenido

Cómo evitar cobros dobles con una clave de idempotencia

Guía/ 14 min de lectura

Una clave por intento de pago, guardada en el servidor junto con su respuesta: un reintento, un doble clic o un timeout cobran una sola vez. Código Node probado.

  • Node.js
  • Bases de datos
En este artículo (8)
  1. Por qué ocurren los cobros dobles
  2. Qué es una clave de idempotencia
  3. Implementación en el cliente: una clave por intento de pago
  4. Implementación en el servidor: guardar la clave y responder igual ante repetidos
  5. Ejemplo completo en Node
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

Para evitar cobros dobles, el cliente genera una clave única por intento de pago y la manda en el encabezado Idempotency-Key. El servidor guarda la clave con la huella del cuerpo y la respuesta; si la misma clave vuelve a llegar, responde lo mismo sin cobrar otra vez. Un doble clic o un timeout cobran una vez.

Aquí vas a ver por qué ocurren, qué dicen Stripe y el borrador de la IETF sobre la clave, y cómo implementarla en Node sin dependencias, con el cliente, el servidor y las pruebas que ejecutamos. Si además vendes unidades limitadas, el problema hermano es vender lo que no tienes: lo resolvemos en cómo evitar la sobreventa de inventario.

Por qué ocurren los cobros dobles

Un cobro doble casi nunca es un error del procesador de pagos. Es tu sistema mandando dos veces la misma orden de cobro, por una de estas tres razones:

  • Doble clic. El cliente toca «Pagar», la página tarda y vuelve a tocar. Salen dos POST idénticos casi al mismo tiempo.
  • Reintentos automáticos. Tu código de fetch, un SDK, un proxy o una cola reintentan una petición que creen fallida. Los SDK de Stripe, por ejemplo, pueden generar claves y reintentar solos.
  • Timeouts. El servidor cobró, pero la respuesta se perdió en el camino: la red del celular, un balanceador que cortó la conexión. El cliente ve un error, no sabe si se cobró y reintenta.

El tercer caso es el que más cuesta, porque desactivar el botón no lo arregla. La guía de manejo de errores de Stripe lo dice sin rodeos: cuando falla una conexión, no sabes si el servidor recibió o ejecutó la petición. Que la respuesta no llegue no significa que el cobro no ocurrió.

el mismo timeout, sin clave y con clavesin claveclienteservidorPOST /paymentscobro 1respuesta perdidatimeoutPOST (reintento)cobro 2201 · ch_2Idempotency-Key: KclienteservidorPOST · Kcobra, guarda Krespuesta perdidatimeoutPOST · K (reintento)K existe: repite201 · el mismo ch_1sin clave: 2 cobros · con clave: 1 cobroel reintento repite la clave y el servidor repite la respuesta

Desliza la figura para verla completa

La solución no es dejar de reintentar, sino que reintentar sea seguro: que el servidor reconozca la segunda petición como la misma operación y no la ejecute dos veces.

Qué es una clave de idempotencia

Una operación es idempotente si hacerla varias veces deja el mismo resultado que hacerla una. Según RFC 9110, que cita el borrador de la IETF, GET, PUT y DELETE lo son; POST y PATCH, no. Un cobro es un POST: dos peticiones, dos cobros.

Una clave de idempotencia es una cadena única que el cliente genera para una operación y manda con cada intento de esa operación. El servidor la usa para reconocer los reintentos: la primera vez procesa; las siguientes devuelve lo que ya respondió. Hay dos referencias que conviene leer:

TemaStripe (API v1)Borrador IETF -08
EncabezadoIdempotency-KeyIdempotency-Key
FormatoHasta 255 caracteres; sugiere UUID v4 o una cadena aleatoria con suficiente entropíaUn String de Structured Fields, entre comillas; recomienda un UUID o un identificador aleatorio parecido
Cuánto duraAl menos 24 horas; después puede borrarla, y la misma clave crea una petición nuevaCada API define su política de expiración y la publica
Misma clave, otro cuerpoError: compara los parámetros con los de la petición original422 Unprocessable Content
Misma clave, petición en curso409 Conflict, sin guardar resultado409 Conflict
Sin claveNada que deduplicar: cada POST es nuevo400 Bad Request si la API la exige
Qué peticionesTodos los POST; en GET y DELETE no tiene efectoMétodos no idempotentes, como POST y PATCH

Dos detalles de Stripe que vale la pena copiar. Guarda el código de estado y el cuerpo de la primera respuesta en cuanto empieza a ejecutar la petición, incluidos los errores 500, y marca las repeticiones con Idempotent-Replayed: true. Y si los parámetros no pasan la validación, o hay otra petición con la misma clave en curso, no guarda nada: puedes reintentar con la misma clave.

la vida de una clave de idempotencianuevael cliente la creacrypto.randomUUID()en cursoreservada al llegarrepetidas: 409completadarespuesta guardadarepetidas: la mismacaducadaStripe: ≥ 24 hluego, petición nuevalo que guarda el servidorkey8e03978e-40d5-…fingerprintsha256(cuerpo)status201body{"id":"ch_1",…}el clientecrea K al empezar el pagola repite en cada reintentonueva K: solo otro pagola clave nombra el intento, no la peticiónStripe la guarda al menos 24 h; el borrador IETF deja el plazo a cada API

Desliza la figura para verla completa

Implementación en el cliente: una clave por intento de pago

La regla del cliente cabe en una línea: la clave nace cuando empieza el intento de pago y se reutiliza en cada reintento y en cada clic repetido de ese intento. Una clave nueva por petición no protege nada. Este es el cliente completo, client.mjs:

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function postPayment(url, payment, key, { retries = 3, timeoutMs = 10000 } = {}) {
  for (let attempt = 0; ; attempt++) {
    try {
      const res = await fetch(url, {
        method: "POST",
        headers: { "content-type": "application/json", "idempotency-key": key },
        body: JSON.stringify(payment),
        signal: AbortSignal.timeout(timeoutMs),
      });
      if ([409, 502, 503, 504].includes(res.status) && attempt < retries) {
        await sleep(200 * 2 ** attempt);
        continue;
      }
      return { status: res.status, replayed: res.headers.get("idempotent-replayed") === "true", body: await res.json() };
    } catch (err) {
      if (attempt >= retries) throw err;
      await sleep(200 * 2 ** attempt);
    }
  }
}

let key = null;

export async function onPay(payment, url = "/payments") {
  key ??= crypto.randomUUID();
  const result = await postPayment(url, payment, key);
  if (result.status < 500 && result.status !== 409) key = null;
  return result;
}
  1. postPayment recibe la clave como argumento y nunca la inventa: todos sus reintentos mandan la misma clave y el mismo cuerpo.
  2. AbortSignal.timeout(timeoutMs) corta la espera. Un timeout no dice si se cobró, y por eso se reintenta con la misma clave.
  3. Reintenta 409 (otra petición con la clave sigue en curso) y 502, 503 y 504 (el servidor no llegó a responder), con espera exponencial de 200, 400 y 800 ms. Un 500 no se reintenta: el servidor ya guardó esa respuesta y la repetiría igual.
  4. Un error de red, el catch, también se reintenta con la misma clave, hasta retries veces. Después lanza el error.
  5. replayed lee el encabezado idempotent-replayed que manda nuestro servidor, el mismo nombre que usa Stripe.
  6. onPay es lo que conectas al botón «Pagar». key ??= crypto.randomUUID() crea la clave solo si no hay una: el segundo clic de un doble clic reutiliza la del primero.
  7. Tras una respuesta definitiva (un 201 o un 4xx que no sea 409), la clave se descarta y la próxima compra lleva otra. Tras un error de red, un 409 o un 5xx, se conserva: el siguiente clic repite el mismo intento, no abre uno nuevo.

crypto.randomUUID() devuelve un UUID v4 hecho con un generador criptográficamente seguro, pero según MDN solo existe en contextos seguros (HTTPS). Y sí, desactiva el botón mientras se procesa: es buena experiencia de uso, pero no sustituye a la clave, porque no evita ni los reintentos ni los timeouts.

Implementación en el servidor: guardar la clave y responder igual ante repetidos

El servidor hace cuatro cosas en orden: valida, calcula la huella del cuerpo, busca la clave y, si es nueva, la reserva antes de cobrar. Este es el servidor completo, server.mjs, con node:http y sin dependencias:

import { createServer } from "node:http";
import { createHash } from "node:crypto";

export function createPaymentServer(charge) {
  const keys = new Map();

  const send = (res, status, body, headers = {}) => {
    res.writeHead(status, { "content-type": "application/json", ...headers });
    res.end(JSON.stringify(body));
  };

  return createServer(async (req, res) => {
    if (req.method !== "POST" || req.url !== "/payments") return send(res, 404, { error: "not found" });

    const key = req.headers["idempotency-key"];
    if (!key || key.length > 255) return send(res, 400, { error: "Idempotency-Key is missing or too long" });

    let raw = "";
    for await (const chunk of req) raw += chunk;
    let payment;
    try {
      payment = JSON.parse(raw);
    } catch {
      return send(res, 400, { error: "body is not JSON" });
    }
    if (!Number.isInteger(payment?.amount) || payment.amount <= 0 || !/^[a-z]{3}$/.test(payment.currency)) {
      return send(res, 400, { error: "amount (integer, cents) and currency (e.g. mxn) are required" });
    }
    const fingerprint = createHash("sha256").update(raw).digest("hex");

    const saved = keys.get(key);
    if (saved) {
      if (saved.fingerprint !== fingerprint) return send(res, 422, { error: "Idempotency-Key already used with another body" });
      if (!saved.done) return send(res, 409, { error: "a request with this Idempotency-Key is in progress" });
      return send(res, saved.status, saved.body, { "idempotent-replayed": "true" });
    }

    keys.set(key, { fingerprint, done: false });

    let status, body;
    try {
      body = await charge(payment);
      status = 201;
    } catch {
      status = 500;
      body = { error: "payment outcome unknown; check the order before trying again" };
    }
    keys.set(key, { fingerprint, done: true, status, body });
    send(res, status, body);
  });
}
  1. keys es un Map en memoria con una entrada por clave, y send responde JSON con los encabezados que le pases.
  2. Sin clave, o con más de 255 caracteres (el límite de Stripe), responde 400, como recomienda el borrador.
  3. Lee el cuerpo y lo valida: amount entero y positivo, en centavos; currency de tres letras. Un cuerpo inválido recibe 400 y no se guarda nada, igual que en Stripe: el cliente puede corregirlo y reintentar con la misma clave.
  4. fingerprint es el SHA-256 del cuerpo tal como llegó. Es la huella que menciona el borrador: detecta una clave reutilizada con otro contenido.
  5. Si la clave ya existe: con otra huella, 422; todavía en curso, 409; terminada, devuelve el estado y el cuerpo guardados, con idempotent-replayed: true.
  6. keys.set(key, { fingerprint, done: false }) reserva la clave antes de llamar al proveedor. Entre keys.get y keys.set no hay ningún await, así que en un proceso de Node dos peticiones con la misma clave no pueden pasar ambas por ese punto.
  7. charge(payment) es tu llamada al proveedor de pagos. Si falla, el 500 también se guarda: el resultado es desconocido y un reintento no debe cobrar de nuevo. Es lo que hace Stripe.
  8. Al final guarda el estado y el cuerpo, y responde.
qué responde el servidor en cada casollegala claverespuestacobrasin clave—400noclave nuevase reserva201símisma clave, otro cuerpoexiste422nomisma clave, en cursoen curso409nomisma clave, terminadacompletadala guardadanoclave caducadaborradacomo nuevasísolo una petición por clave llega al proveedorcódigos del borrador IETF -08; la repetida añade idempotent-replayed

Desliza la figura para verla completa

Con más de una instancia

El Map vive en la memoria de un proceso: se pierde al reiniciar y no se comparte entre instancias. Nuestra recomendación para producción: una tabla compartida con la clave como PRIMARY KEY, reservada con INSERT ... ON CONFLICT (key) DO NOTHING RETURNING key. La restricción de unicidad deja insertar la fila a una sola petición, y RETURNING solo devuelve filas insertadas (ver la documentación de INSERT de PostgreSQL). Es la misma reserva del Map, pero en la base de datos. Ese SQL no forma parte del código que probamos aquí. Define también cuánto guardas cada clave (Stripe: al menos 24 horas) y borra las viejas.

Y manda también una clave a tu proveedor. Si tu servidor llama a Stripe y esa llamada hace timeout, tu propio reintento hacia Stripe es otro cobro posible. Stripe acepta Idempotency-Key en todos sus POST: usa una clave estable por intento, como la que te mandó el cliente.

Ejemplo completo en Node

El ejemplo completo son tres archivos: el cliente y el servidor de arriba, y demo.mjs, que arranca el servidor con un proveedor falso que tarda 300 ms y numera cada cobro. Lo probamos con Node 22 en Windows 11.

import { createPaymentServer } from "./server.mjs";

let charges = 0;
const charge = async ({ amount, currency }) => {
  await new Promise((resolve) => setTimeout(resolve, 300));
  return { id: `ch_${++charges}`, amount, currency, status: "succeeded" };
};

createPaymentServer(charge).listen(8787, () => console.log("POST http://localhost:8787/payments"));

Arráncalo con node demo.mjs y, en otra terminal con bash (en Windows sirve Git Bash), corre bash curl.sh:

KEY=8e03978e-40d5-43e8-bc93-6894a57f9324
BODY='{"orderId":"A-1001","amount":129900,"currency":"mxn"}'
pay() { curl -s http://localhost:8787/payments -H "content-type: application/json" -H "Idempotency-Key: $1" -d "$2" -w '  -> %{http_code} %header{idempotent-replayed}\n'; }

pay $KEY "$BODY"
pay $KEY "$BODY"
pay $KEY '{"orderId":"A-1001","amount":1,"currency":"mxn"}'
pay other-key "$BODY" & pay other-key "$BODY"; wait

Esta es la salida que obtuvimos:

{"id":"ch_1","amount":129900,"currency":"mxn","status":"succeeded"}  -> 201 
{"id":"ch_1","amount":129900,"currency":"mxn","status":"succeeded"}  -> 201 true
{"error":"Idempotency-Key already used with another body"}  -> 422 
{"error":"a request with this Idempotency-Key is in progress"}  -> 409 
{"id":"ch_2","amount":129900,"currency":"mxn","status":"succeeded"}  -> 201
  1. Primer pago: 201 y el cobro ch_1.
  2. Mismo pedido con la misma clave: la misma respuesta, el mismo ch_1, marcada como repetida. El proveedor no cobró otra vez.
  3. La misma clave con otro monto: 422, y no se cobra.
  4. Dos peticiones simultáneas con la clave other-key: una recibe 409 mientras la otra cobra ch_2. El orden de esas dos líneas puede cambiar en cada corrida.

Nuestras 11 pruebas, en payments.test.mjs con el corredor de pruebas de Node, cuentan los cobros del proveedor falso en cada caso y pasaron con node --test payments.test.mjs: reintento con la misma clave, misma clave con otro cuerpo, dos peticiones simultáneas, timeout del cliente, doble clic y un cobro que falla. La que más enseña es la que manda el mismo pedido con dos claves distintas: cobra dos veces. La clave solo protege si el reintento la repite.

Errores comunes

  • Generar una clave nueva en cada reintento. Es el error más común, y la prueba lo demuestra: dos claves, dos cobros. La clave pertenece al intento de pago, no a la petición.
  • Guardar la clave después de cobrar. Si la reservas al final, dos peticiones simultáneas pasan las dos la búsqueda y cobran las dos. Resérvala antes de llamar al proveedor.
  • Comparar solo la clave. Sin la huella del cuerpo, un error del cliente que reutiliza la clave con otro monto recibe la respuesta del pago anterior como si fuera la suya. Responde 422.
  • Borrar la clave cuando el cobro falla con un error desconocido. Si el proveedor sí cobró y tú borraste la clave, el reintento cobra otra vez. Guarda el 500 y concilia el pedido antes de abrir otro intento.
  • Usar datos personales como clave, o mezclar las de todos los clientes. Stripe pide evitar correos o identificadores personales; un UUID aleatorio no revela nada. Y nuestra recomendación: guarda cada clave junto a la cuenta que la envió, para que nadie reciba la respuesta guardada de otro.
  • Creer que desactivar el botón basta. Ayuda con el doble clic, pero no con los reintentos ni con los timeouts.

Preguntas frecuentes

¿Cuánto tiempo hay que guardar cada clave?

El borrador de la IETF deja que cada API lo decida y pide publicarlo. Stripe guarda sus claves al menos 24 horas y después puede borrarlas; una clave reutilizada tras ese borrado crea una petición nueva. Nuestra recomendación para un checkout: 24 horas, que cubren los reintentos de un intento de pago.

¿La clave va entre comillas?

El borrador define el valor como un String de Structured Fields, así que lo escribe entre comillas: Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324". Los ejemplos de Stripe lo mandan sin comillas. Para tu propia API, trata el valor como una cadena opaca y documenta qué formato esperas: mientras el cliente repita exactamente el mismo valor, funciona.

¿Necesito clave en GET o DELETE?

No. Stripe indica que en GET y DELETE no tiene efecto porque ya son idempotentes, y el borrador apunta a POST y PATCH. Ponla en todo lo que cree o cobre algo.

¿Qué hago si el primer intento devolvió un 500?

Trátalo como resultado desconocido: el cobro pudo ocurrir. Stripe recomienda no reintentar con una clave nueva hasta conciliar lo que pasó, por ejemplo con los webhooks o consultando el objeto. Nuestro servidor guarda el 500 para que un reintento con la misma clave no vuelva a cobrar.

Checklist

  • El cliente crea la clave al empezar el intento de pago, con crypto.randomUUID().
  • Los reintentos y los clics repetidos de ese intento mandan la misma clave y el mismo cuerpo.
  • El servidor reserva la clave antes de cobrar, en un almacén compartido si tienes varias instancias.
  • Guardas la huella del cuerpo y respondes 422 si cambia.
  • Una petición en curso con la misma clave recibe 409, y el cliente la reintenta.
  • Las respuestas repetidas son iguales a la original, también los errores 500.
  • Las claves caducan según una política escrita (por ejemplo, 24 horas).
  • Tu servidor también manda una clave estable al proveedor de pagos.

Con la clave, un reintento deja de ser un riesgo y pasa a ser la forma normal de recuperarse de una red que falla. El siguiente punto débil del checkout suele ser el inventario: cómo evitar la sobreventa cuando dos clientes compran la última unidad. Y recuerda que este endpoint necesita autenticación propia: CORS no protege tu API. Si vas a hacer este cambio con un agente, pídele primero un plan con plan mode en Claude Code.

¿Viste esto en Instagram? Comenta PAGOS en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 30 de octubre de 2026 · actualizado el 1 de noviembre de 2026

← Blog