Idempotencia

Envía un Idempotency-Key estable por intención de creación. Reutiliza exactamente la misma clave y cuerpo compatible al reintentar una respuesta perdida; una intención nueva necesita otra clave. El contrato conserva la respuesta original por 72 horas y devuelve 409 si la clave se usa con otro cuerpo.

import { createTimbroPayments } from "@timbro/payments";

const secretKey = process.env.TIMBRO_PAYMENTS_SECRET_KEY;
if (!secretKey) throw new Error("Missing TIMBRO_PAYMENTS_SECRET_KEY");
const timbro = createTimbroPayments({ secretKey });
const idempotencyKey = "create-order-123";
const payment = await timbro.payments.create({
  idempotencyKey,
  saleReference: "order-123",
  amount: { currency: "DOP", minorUnits: 125_000 },
  description: "Servicio de mantenimiento",
  fiscalDocument: null,
});

La idempotencia no convierte un resultado incierto en rechazo. Si la red se corta después de enviar, consulta el pago antes de decidir si mostrar un resultado o pedir otra acción.

Persiste la clave junto a la intención normalizada. Un 500, 502, timeout o conexión rota conserva la misma clave para el reintento; una respuesta 201 aceptada la cierra. Nunca cambies sólo la clave para escapar de un error sin reconciliar el Payment.