---
title: "Reembolsar un pago | Timbro"
description: "Devuelve el dinero de un pago y confirma el resultado"
canonical: "https://timbro.do/docs/cobros/reembolsos/"
---

Cobrar

# Reembolsar un pago

Para devolver el dinero de un pago confirmado, primero [lee `refundable`](https://timbro.do/docs/cobros/reembolsos/#antes-de-reembolsar-lee-refundable) para saber si el dinero se devolverá sin que intervenga el equipo de Timbro. Luego usa el `id` del pago y una referencia que identifique este reembolso en tu sistema:

- [TypeScript](https://timbro.do/docs/cobros/reembolsos/#tab-panel-0-0)
- [Python](https://timbro.do/docs/cobros/reembolsos/#tab-panel-0-1)

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

const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY! });
const refund = await timbro.refunds.create({
  paymentId: "payment_123456789abcdefghjkmnpqr",
  refundReference: "order-123-return-1",
});
```

```python
import os

from timbro_payments import TimbroPayments

timbro = TimbroPayments(api_key=os.environ["TIMBRO_PAYMENTS_SECRET_KEY"])
refund = timbro.refunds.create({
    "paymentId": "payment_123456789abcdefghjkmnpqr",
    "refundReference": "order-123-return-1",
})
```

Si no envías `amount`, solicitas todo lo que queda por devolver de ese pago. Timbro aparta ese monto al aceptar la solicitud, para que otro reembolso no use el mismo dinero.

Si pierdes la respuesta, repite la solicitud con el mismo `refundReference`: recibirás el mismo reembolso y su estado actual. También puedes encontrarlo sin repetir la solicitud: lista los reembolsos con los filtros exactos `paymentId` y `refundReference`. No uses una referencia nueva para recuperar una solicitud anterior.

Para solicitar solo una parte del dinero, añade `amount: { currency: "DOP", value: "100.00" }` y el ITBIS exacto del reembolso en `taxAmount`, por ejemplo `{ currency: "DOP", value: "15.25" }`. Usa el impuesto de los artículos devueltos o de la nota de crédito; Timbro no calcula una proporción estimada. No puedes cambiar el monto de un reembolso ya creado. Antes de elegir el monto, lee `refundable`, como se explica a continuación.

## Antes de reembolsar, lee `refundable`

Un pago `succeeded` incluye `refundable`. Consúltalo antes de llamar a `POST /v1/refunds` para saber qué hará Timbro con cada monto:

- [TypeScript](https://timbro.do/docs/cobros/reembolsos/#tab-panel-1-0)
- [Python](https://timbro.do/docs/cobros/reembolsos/#tab-panel-1-1)

```ts
const payment = await timbro.payments.retrieve("payment_123456789abcdefghjkmnpqr");
const automaticAmount = payment.refundable?.automaticAmount ?? null;

if (automaticAmount !== null) {
  await timbro.refunds.create({
    paymentId: payment.id,
    refundReference: "order-123-return-1",
    amount: automaticAmount,
  });
}
```

```python
payment = timbro.payments.retrieve("payment_123456789abcdefghjkmnpqr")
refundable = payment["refundable"]
automatic_amount = refundable["automaticAmount"] if refundable else None

if automatic_amount is not None:
    timbro.refunds.create({
        "paymentId": payment["id"],
        "refundReference": "order-123-return-1",
        "amount": automatic_amount,
    })
```

- `refundable.amount` es el saldo que un reembolso nuevo puede apartar: lo capturado, menos los reembolsos en curso, exitosos, en verificación o en `operator_required`.
- `refundable.automaticAmount` es el único monto cuyo reembolso mueve el dinero sin que intervenga el equipo de Timbro. Es `null` cuando todo reembolso necesita al equipo de Timbro.
- `refundable` es `null` hasta que el pago llega a `succeeded`.

Si `automaticAmount` tiene valor, envía ese monto en `amount`. Timbro devuelve el dinero y el reembolso llega a `succeeded` sin intervención del equipo de Timbro.

Si `automaticAmount` es `null`, o si envías otro monto, Timbro acepta la solicitud, pero crea el reembolso en `operator_required`: mantiene apartado el monto y el equipo de Timbro devuelve el dinero. Decide antes de crearlo:

- Si el cliente necesita el dinero ahora, devuélvelo por otro medio, por ejemplo en efectivo, y no crees también el reembolso en Timbro.
- Si puede esperar, crea el reembolso con tu `refundReference` y deja que el equipo de Timbro actúe. Recibirás `refund.operator_required` cuando quede esperando al equipo de Timbro.

## Si el pago tiene propina voluntaria

Un pago solo ofrece propina voluntaria si incluye un artículo con propina legal y activas `checkoutPreferences.tips`, como explica [Ofrecer propina voluntaria](https://timbro.do/docs/cobros/impuestos-y-articulos/#ofrecer-propina-voluntaria).

`amount` es el total del reembolso, incluida cualquier propina que devuelvas. En un reembolso parcial, omitir `voluntaryTipAmount` devuelve cero propina voluntaria. Para devolver RD$ 100.00, de los cuales RD$ 20.00 son propina, usa:

- [TypeScript](https://timbro.do/docs/cobros/reembolsos/#tab-panel-2-0)
- [Python](https://timbro.do/docs/cobros/reembolsos/#tab-panel-2-1)

```ts
const partialRefund = await timbro.refunds.create({
  paymentId: "payment_123456789abcdefghjkmnpqr",
  refundReference: "order-123-return-2",
  amount: { currency: "DOP", value: "100.00" },
  voluntaryTipAmount: { currency: "DOP", value: "20.00" },
});
```

```python
partial_refund = timbro.refunds.create({
    "paymentId": "payment_123456789abcdefghjkmnpqr",
    "refundReference": "order-123-return-2",
    "amount": {"currency": "DOP", "value": "100.00"},
    "voluntaryTipAmount": {"currency": "DOP", "value": "20.00"},
})
```

Si omites `amount` para devolver todo el saldo restante, también se devuelve la propina voluntaria restante por defecto, y el reembolso se reporta como `kind: "full"` aunque antes hubiera un reembolso parcial. Un reembolso por el total capturado también incluye la propina restante por defecto. La porción de venta y la de propina deben caber en sus respectivos saldos. La propina legal forma parte de la venta; `voluntaryTipAmount` solo identifica la propina voluntaria.

La nota de crédito (E34) debe usar el monto fiscal de la venta devuelta y excluir la propina voluntaria. Emitirla y devolver el dinero son tareas separadas. Después de emitirla, asóciala al reembolso:

```ts
await timbro.refunds.attachInvoice({
  refundId: refund.id,
  invoiceId: "f35b7ae4-c484-4c63-981e-4f0f15e913b5",
  idempotencyKey: "order-123-return-2-credit-note",
});
```

Timbro valida que el total de la nota de crédito sea el monto del reembolso menos la propina voluntaria devuelta y que su ITBIS coincida con el ITBIS del reembolso, cuando se conoce. Esta asociación no cambia el resultado del reembolso.

## Qué puede ejecutarse automáticamente

`refundable.automaticAmount` tiene valor solo cuando se cumplen todas estas condiciones:

- El pago es del modo de prueba, en pesos dominicanos (DOP), con tarjeta y sin división.
- El reembolso es por el total capturado.
- El pago no tiene reembolsos anteriores, salvo los rechazados.
- El pago y el reembolso pasan por Azul o CardNet, con la afiliación y las credenciales del pago original.

`refundable.automaticPartial` indica por separado si el pago permite un reembolso menor, con los límites `maximumAmount` y `maximumTaxAmount`. Actualmente admite un reembolso parcial de una venta Azul en DOP, en modo de prueba, si envías el `taxAmount` exacto. El monto debe ser menor al total cobrado y el ITBIS no puede superar el monto devuelto ni el impuesto del pago original. Repite ambos valores sin cambios al recuperar una solicitud.

Los reembolsos parciales por CardNet o de montos retenidos que luego se cobraron, los parciales sin impuesto exacto, los pagos divididos, los pagos en vivo, los pagos con Apple Pay o Google Pay y los pagos con un reembolso anterior completado o pendiente quedan en `operator_required`. Lo mismo ocurre si a la afiliación le falta la evidencia de la captura o las credenciales de reembolso; en ese caso no se intenta mover dinero. Escribe al equipo de Timbro para continuar esos casos.

Timbro devuelve el dinero a través de la misma afiliación de Azul o CardNet que hizo el pago, aunque después configures otra afiliación para nuevos pagos.

## Confirmar el resultado

- [TypeScript](https://timbro.do/docs/cobros/reembolsos/#tab-panel-3-0)
- [Python](https://timbro.do/docs/cobros/reembolsos/#tab-panel-3-1)

```ts
const current = await timbro.refunds.retrieve(refund.id);
```

```python
current = timbro.refunds.retrieve(refund["id"])
```

`succeeded` confirma que se devolvió el dinero. Si recibes `pending`, `processing` o `verifying`, espera y vuelve a consultar el mismo reembolso. Si el resultado sigue sin conocerse, no crees otro: el primero podría completarse. `declined` indica que fue rechazado; `operator_required` indica que el reembolso mantiene apartado el monto y necesitas ayuda del equipo de Timbro.

Para no consultar en un ciclo, suscribe tu [webhook](https://timbro.do/docs/cobros/webhooks/) a `refund.succeeded` y `refund.declined`. Al recibir uno, consulta el reembolso con `event.data.id` y usa ese estado.

Devolver el dinero no emite un e-CF. Si la venta requiere una nota de crédito, emítela con el tipo E34 en `/v1/invoices` y conserva por separado el resultado del reembolso. Luego asocia la nota con `refunds.attachInvoice`.

[Página anterior\
Cobrar con QR](https://timbro.do/docs/cobros/qr-y-nfc/)[Siguiente página\
Conecta tu afiliación](https://timbro.do/docs/negocio/conectar-afiliacion/)

Vende, atiende a tus clientes y cobra desde tu celular

© 2026 Timbro. Todos los derechos reservados

[Español](https://timbro.do/docs/cobros/reembolsos/)[English](https://timbro.do/en/docs/cobros/reembolsos/)

## 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/)<hola@timbro.do>

## 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/)