Idempotency

Send a stable Idempotency-Key per creation intent. Reuse exactly the same key and compatible body when retrying a lost response; a new intent needs a new key. The contract retains the original response for 72 hours and returns 409 when the key is reused with a different body.

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: "Maintenance service",
  fiscalDocument: null,
});

Idempotency does not turn an uncertain result into a rejection. If the network fails after sending, query the payment before showing a result or asking for another action.

Persist the key beside the normalized intent. A 500, 502, timeout, or broken connection retains the same key for retry; an accepted 201 closes it. Do not change only the key to escape an error without reconciling the Payment.