--- title: "Crear un pago | Timbro" description: "Crea un link de pago para que tu cliente pague con Timbro" canonical: "https://timbro.do/docs/empieza/primer-pago/" --- Empieza # 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](https://timbro.do/docs/cobros/impuestos-y-articulos/) configurado. Guarda la clave en `TIMBRO_PAYMENTS_SECRET_KEY`, en tu servidor. Si te falta alguno de estos pasos, [prepara tu cuenta](https://timbro.do/docs/empieza/antes-de-integrar/). - [TypeScript](https://timbro.do/docs/empieza/primer-pago/#tab-panel-0-0) - [Python](https://timbro.do/docs/empieza/primer-pago/#tab-panel-0-1) Instala el SDK en un proyecto con Node.js 24.19 o posterior: ```sh npm install @timbro/payments ``` Esta ruta `POST` crea el pago y lleva al cliente al Checkout, la página donde pagará: ```ts 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); } ``` Instala el SDK en un proyecto con Python 3.11 o posterior: ```sh 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: ```python 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: ```python 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](https://timbro.do/docs/cobros/qr-y-nfc/#define-cu%C3%A1nto-tiempo-queda-abierto-el-qr). 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 ```sh 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](https://timbro.do/docs/cobros/consultar-pagos/) 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](https://timbro.do/docs/cobros/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](https://timbro.do/docs/empieza/como-funciona/). [Página anterior\ Preparar tu cuenta](https://timbro.do/docs/empieza/antes-de-integrar/)[Siguiente página\ Configurar la facturación](https://timbro.do/docs/comprobantes/configurar-facturacion/) Vende, atiende a tus clientes y cobra desde tu celular © 2026 Timbro. Todos los derechos reservados [Español](https://timbro.do/docs/empieza/primer-pago/)[English](https://timbro.do/en/docs/empieza/primer-pago/) ## Productos [Facturación](https://timbro.do/facturacion-electronica/)[Atiende](https://timbro.do/atiende/)[Cobra](https://timbro.do/pagos/)[Portal Timbro](https://timbro.do/portal-timbro/)[Integraciones](https://timbro.do/integraciones/)[Cuenta Timbro](https://timbro.do/cuenta-timbro/)[Precios](https://timbro.do/precios/) ## Desarrolladores [SDK y API](https://timbro.do/desarrolladores/)[Documentación](https://timbro.do/docs/)[Referencia de la API](https://timbro.do/docs/reference/payments/) ## Empresa [INDEXA, la empresa detrás de Timbro](https://indexa.do/)[Presentaciones](https://timbro.do/presentaciones/) ## Ayuda [Cómo empezar](https://timbro.do/como-empezar/)[Guía de facturación electrónica](https://timbro.do/guias/facturacion-electronica-republica-dominicana/)[Contacto](https://timbro.do/contacto/) ## Legal [Condiciones para negocios](https://timbro.do/politicas/negocios/)[Política de uso](https://timbro.do/politicas/uso/)[Privacidad](https://timbro.do/politicas/privacidad/)[Seguridad](https://timbro.do/politicas/seguridad/)[Todos los documentos](https://timbro.do/politicas/)