Tu primer pago

El servidor del comercio crea un Payment con importe en unidades menores, referencia de venta y la intención fiscal. Esta llamada usa una clave secreta sólo en el servidor:

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 payment = await timbro.payments.create({
  idempotencyKey: "create-order-123",
  saleReference: "order-123",
  amount: { currency: "DOP", minorUnits: 125_000 },
  description: "Servicio de mantenimiento",
  fiscalDocument: null,
});

Entrega nextAction.url al comprador sin reconstruir el formulario. Los ocho estados canónicos de Payment son requires_customer_action, processing, partially_paid, verifying, succeeded, declined, canceled y expired. verifying es un resultado incierto no terminal: consulta el mismo Payment y no cobres de nuevo. declined es una respuesta válida de creación, no un error HTTP que deba repetirse automáticamente.

La autorización monetaria, la emisión fiscal, la disponibilidad del PDF y la entrega por correo son ciclos observables separados. Un pago succeeded puede coexistir con un FiscalDocument processing, rejected u operator_required.

En TypeScript, conserva la referencia y consulta después de volver de Checkout:

const current = await timbro.payments.retrieve(payment.id);
if (current.status === "verifying") {
  // Persist the payment and schedule retrieval; never create a second payment.
}