---
title: "Create a payment | Timbro"
description: "Create a payment link and send the customer to Checkout"
canonical: "https://timbro.do/en/docs/empieza/primer-pago/"
---

Get started

# Create a payment

You need an active merchant account, an `sk_test_…` secret key, and a [default tax](https://timbro.do/en/docs/cobros/impuestos-y-articulos/) configured for your merchant. Store the key in `TIMBRO_PAYMENTS_SECRET_KEY` on your server only. [Prepare your account](https://timbro.do/en/docs/empieza/antes-de-integrar/) if you have not done that yet.

- [TypeScript](https://timbro.do/en/docs/empieza/primer-pago/#tab-panel-0-0)
- [Python](https://timbro.do/en/docs/empieza/primer-pago/#tab-panel-0-1)

Install the SDK in a project with Node.js 24.19 or later:

```sh
npm install @timbro/payments
```

In a server route that returns a `Response`:

```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: "Maintenance service",
    returnUrl: "https://merchant.example/orders/123",
  });
  return Response.redirect(payment.checkout.url);
}
```

Install the SDK in a project with Python 3.11 or later:

```sh
pip install timbro-payments
```

This program creates the payment and prints the Checkout link where the customer pays. `TimbroPayments` is the synchronous client, which ERPs usually use:

```python
import os

from timbro_payments import TimbroPayments

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

`application` is optional: it adds your integration’s name and version to the `User-Agent` header. Requests and responses are dictionaries with the API’s field names, and amounts are strings.

If your server uses `asyncio`, `AsyncTimbroPayments` has the same methods. `await` each call:

```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": "Maintenance service",
            "returnUrl": "https://merchant.example/orders/123",
        })
        print(payment["id"], payment["checkout"]["url"])


asyncio.run(main())
```

The Python examples in the other guides use the synchronous client.

`amount` is the total, including tax. Use a different reference for each collection request and keep it the same when retrying. Save the payment `id` with the order.

Checkout stays open for 30 minutes with a `returnUrl` and 1 hour without one. To change that, send `expiresAfterSeconds` with a value from 300 to 86400 seconds, and read the deadline from `expiresAt` on the payment. A POS, for example, sends `600`. [More about the window](https://timbro.do/en/docs/cobros/qr-y-nfc/#choose-how-long-the-qr-code-stays-open).

These windows apply to ordinary payments. The first payment for a Subscription has a fixed 24-hour window; when it expires, the Subscription is terminal, so create another one with a new `subscriptionReference`. Automatic payments start with both `expiresAt` and `checkout.expiresAt` set to `null`. Timbro sets a 7-day deadline when the email provider accepts the pending payment notice. Do not show a countdown while the deadline is `null`, and resending the notice does not extend a deadline that is already set.

Use HTTP directly

```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": "Maintenance service",
    "returnUrl": "https://merchant.example/orders/123"
  }'
```

The response includes `id` and `checkout.url`. You do not need to send an idempotency key for this operation.

## Confirm the payment

Returning to `returnUrl` in the browser does not confirm the payment. [Retrieve the payment](https://timbro.do/en/docs/cobros/consultar-pagos/) from your server and apply the payment once when its status is `succeeded`. Use [webhooks](https://timbro.do/en/docs/cobros/webhooks/) to receive the notification even if the customer closes the tab.

This example creates a payment without an invoice. If the sale needs an invoice, [choose how to integrate your system](https://timbro.do/en/docs/empieza/como-funciona/).

[Previous\
Prepare your account](https://timbro.do/en/docs/empieza/antes-de-integrar/)[Next\
Set up invoicing](https://timbro.do/en/docs/comprobantes/configurar-facturacion/)

Sell, serve your customers, and collect payments from your phone

© 2026 Timbro. All rights reserved

[Español](https://timbro.do/docs/empieza/primer-pago/)[English](https://timbro.do/en/docs/empieza/primer-pago/)

## Products

[Invoicing](https://timbro.do/en/facturacion-electronica/)[Serve](https://timbro.do/en/atiende/)[Collect](https://timbro.do/en/pagos/)[Portal Timbro](https://timbro.do/en/portal-timbro/)[Integrations](https://timbro.do/en/integraciones/)[Cuenta Timbro](https://timbro.do/en/cuenta-timbro/)[Pricing](https://timbro.do/en/precios/)

## Developers

[SDKs and API](https://timbro.do/en/desarrolladores/)[Documentation](https://timbro.do/en/docs/)[API reference](https://timbro.do/en/docs/reference/payments/)

## Company

[INDEXA, the company behind Timbro](https://indexa.do/)[Presentations](https://timbro.do/en/presentaciones/)

## Help

[How to start](https://timbro.do/en/como-empezar/)[Electronic invoicing guide](https://timbro.do/en/guias/facturacion-electronica-republica-dominicana/)[Contact](https://timbro.do/en/contacto/)<hola@timbro.do>

## Legal

[Business Terms](https://timbro.do/en/politicas/negocios/)[Terms of use](https://timbro.do/en/politicas/uso/)[Privacy](https://timbro.do/en/politicas/privacidad/)[Security](https://timbro.do/en/politicas/seguridad/)[All documents](https://timbro.do/en/politicas/)