Crear un pago

Para este ejemplo necesitas una afiliación de Azul o CardNet habilitada para pruebas, una clave secreta sk_test_… y el impuesto de tus pagos configurado. Guarda la clave en TIMBRO_PAYMENTS_SECRET_KEY, en tu servidor. Si te falta alguno de estos pasos, prepara tu cuenta.

TypeScript

Instala el SDK en un proyecto con Node.js 24.19 o posterior:

npm install @timbro/payments

Esta ruta POST crea el pago y lleva al cliente al Checkout, la página donde pagará:

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

const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY! });

export async function POST() {
  const payment = await timbro.payments.create({
    paymentReference: "order-123",
    amount: { currency: "DOP", value: "1250.00" },
    description: "Servicio de mantenimiento",
    returnUrl: "https://merchant.example/orders/123",
  });
  return Response.redirect(payment.checkout.url);
}

Python

Instala el SDK en un proyecto con Python 3.11 o posterior:

pip install timbro-payments

Este programa crea el pago y muestra el link a Checkout, la página donde pagará tu cliente. TimbroPayments es el cliente síncrono, que es el que suelen usar los ERP:

import os

from timbro_payments import TimbroPayments

with TimbroPayments(
    api_key=os.environ["TIMBRO_PAYMENTS_SECRET_KEY"], application="mi-erp/1.0"
) as timbro:
    payment = timbro.payments.create({
        "paymentReference": "order-123",
        "amount": {"currency": "DOP", "value": "1250.00"},
        "description": "Servicio de mantenimiento",
        "returnUrl": "https://merchant.example/orders/123",
    })
    print(payment["id"], payment["checkout"]["url"])

application es opcional y añade el nombre y la versión de tu integración al encabezado User-Agent. Las solicitudes y respuestas son diccionarios con los mismos nombres de campo que la API, y los montos son texto.

Si tu servidor usa asyncio, AsyncTimbroPayments tiene los mismos métodos. Usa await en cada llamada:

import asyncio
import os

from timbro_payments import AsyncTimbroPayments


async def main() -> None:
    async with AsyncTimbroPayments(api_key=os.environ["TIMBRO_PAYMENTS_SECRET_KEY"]) as timbro:
        payment = await timbro.payments.create({
            "paymentReference": "order-123",
            "amount": {"currency": "DOP", "value": "1250.00"},
            "description": "Servicio de mantenimiento",
            "returnUrl": "https://merchant.example/orders/123",
        })
        print(payment["id"], payment["checkout"]["url"])


asyncio.run(main())

Los ejemplos de Python de las demás guías usan el cliente síncrono.

amount es el total que pagará el cliente, con el impuesto incluido. paymentReference identifica este pago en tu sistema. Usa una referencia distinta para cada pago y repítela, con los mismos datos, si necesitas reenviar la solicitud. Guarda el id del pago junto al pedido para consultar el resultado.

El Checkout queda abierto 30 minutos con returnUrl y 1 hora sin él. Para cambiarlo, envía expiresAfterSeconds con un valor de 300 a 86400 segundos; expiresAt en el pago informa el vencimiento. Por ejemplo, un POS envía 600. Más sobre el plazo.

Estos plazos corresponden a pagos normales. El primer pago de una suscripción tiene un plazo fijo de 24 horas; si vence, la suscripción termina y debes crear otra con una subscriptionReference nueva. Los pagos automáticos no tienen expiresAt ni checkout.expiresAt al crearse. Timbro fija un plazo de 7 días cuando el proveedor de email acepta el envío del aviso de pago pendiente; si el vencimiento es null, no muestres una cuenta regresiva. Reenviar el aviso no extiende un plazo ya fijado.

Usar HTTP directamente

curl https://api.timbro.do/v1/payments \
  -H "Authorization: Bearer $TIMBRO_PAYMENTS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentReference": "order-123",
    "amount": { "currency": "DOP", "value": "1250.00" },
    "description": "Servicio de mantenimiento",
    "returnUrl": "https://merchant.example/orders/123"
  }'

La respuesta incluye id y checkout.url. Para reenviar esta solicitud sin crear otro pago, solo tienes que conservar paymentReference y los mismos datos; no necesitas añadir una clave de idempotencia (Idempotency-Key).

Confirma el pago

Cuando el cliente vuelve a returnUrl, todavía debes consultar el pago desde tu servidor. Marca el pedido como pagado solo si recibes status: "succeeded". Si recibes la confirmación más de una vez, evita registrar o entregar el pedido de nuevo. Los webhooks te permiten recibir el aviso aunque el cliente cierre la página.

Este ejemplo crea un pago sin factura. Si la venta lleva factura, elige cómo integrar tu sistema.