Impuestos y artículos

Envía los montos como texto, entre comillas: "1250.00". Ese es el total que pagará el cliente, con el impuesto incluido. Timbro necesita saber qué parte corresponde al impuesto; no añade ITBIS al total ni usa un 18 % cuando no lo has indicado.

Configurar el impuesto habitual

Si todos tus pagos tienen el ITBIS incluido y usan la misma tasa, configúrala una vez para el comercio. El siguiente ejemplo configura un 18 %. Usa la clave de administrador, que permite cambiar esta configuración:

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

const admin = createTimbroPayments({ apiKey: process.env.TIMBRO_ADMIN_KEY! });
const policy = await admin.business.checkoutPolicy.retrieve();
await admin.business.checkoutPolicy.update({
  expectedRevision: policy.revision,
  defaults: { ...policy.defaults, tax: { kind: "itbis_18", included: true } },
  constraints: policy.constraints,
});

También puedes usar itbis_16 (16 %), zero_rated (tasa cero) o exempt (exento). La configuración se guarda por separado en Prueba y En vivo.

El ejemplo conserva las demás opciones del Checkout. expectedRevision evita sobrescribir un cambio hecho por otra persona: si recibes un conflicto, vuelve a consultar la configuración antes de actualizarla.

Con esta configuración puedes crear pagos sin enviar tax. Si una venta combina tasas distintas o incluye cargos adicionales, envía el monto del impuesto o el detalle de los artículos.

Declarar el impuesto de un pago

Para un pago de RD$ 1,250.00 que incluye RD$ 190.68 de ITBIS, añade tax: { includedAmount: "190.68" }. Timbro usará ese monto para este pago, aunque hayas configurado otra tasa. Si el pago no incluye impuesto, envía "0.00".

Si no envías tax y no hay una configuración de impuesto que corresponda a la venta, la API rechaza la solicitud por datos faltantes.

Cobrar artículos

const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_PAYMENTS_SECRET_KEY! });
const payment = await timbro.payments.create({
  paymentReference: "order-124",
  currency: "DOP",
  items: [{
    description: "Café",
    quantity: "2",
    unitPrice: "118.00",
    tax: { kind: "itbis_18", included: true },
  }],
});

El cliente pagará RD$ 236.00, de los cuales RD$ 36.00 son ITBIS. Puedes incluir artículos con tasas distintas o exentos. Si no envías quantity, Timbro usa una unidad.

Timbro calcula los totales con las reglas de la sección siguiente. Si tu sistema ya los calculó, envíalos en expectedTotals: deben coincidir al centavo. Para solicitar un e-CF también debes indicar los datos fiscales de cada artículo, como su unidad de medida y si es un bien o un servicio. Consulta todos los campos en la referencia REST.

Cómo se redondean los totales

Timbro multiplica la cantidad por el precio de cada artículo sin redondear. Luego agrupa los artículos por tasa y según si el precio incluye el ITBIS, y redondea cada grupo una sola vez al centavo. Un medio centavo exacto se redondea hacia arriba.

Grupo	Base	ITBIS
Precios con ITBIS incluido	El total redondeado menos el ITBIS	La suma × 18/118 (o 16/116), redondeada
Precios sin ITBIS	La suma redondeada	La suma × 18 % (o 16 %), redondeada
Tasa cero o exento	La suma redondeada	No aplica

Por ejemplo, con el ITBIS del 18 %:

• Un precio de 100.00 con el ITBIS incluido da una base de 84.75, un ITBIS de 15.25 y un total de 100.00.
• Dos precios sin ITBIS, 10.01 y 10.02, dan una base de 20.03, un ITBIS de 3.61 y un total de 23.64.

Con precios que incluyen el ITBIS, el total del grupo es siempre la suma de sus precios redondeada. Los montos de cada tasa son la suma de sus grupos.

La propina legal es el 10 % de los artículos con legalTip: { applied: true }, cada uno sin su ITBIS incluido: un precio con ITBIS del 18 % se divide entre 1.18 y uno del 16 %, entre 1.16. Los precios sin ITBIS, de tasa cero o exentos cuentan completos. La propina se redondea una sola vez para toda la venta.

El cliente paga las bases, los montos exentos, el ITBIS, la propina legal y los cargos no facturables. Son las mismas cifras del e-CF.

Ofrecer propina voluntaria

Un pago solo ofrece propina voluntaria si la venta incluye un artículo con propina legal y activas checkoutPreferences.tips. Si falta alguno de los dos, la API responde 422 merchant_checkout_policy_invalid en /checkoutPreferences.

const tippedPayment = await timbro.payments.create({
  paymentReference: "order-125",
  currency: "DOP",
  items: [
    {
      description: "Consumo",
      unitPrice: "1000.00",
      tax: { kind: "itbis_18", included: true },
      legalTip: { applied: true },
    },
  ],
  checkoutPreferences: { tips: true },
});

El cliente pagará RD$ 1,084.75: RD$ 1,000.00 de consumo y RD$ 84.75 de propina legal, el 10 % de 1,000.00 / 1.18. La propina voluntaria que elija se suma a ese total.

Para reembolsar un pago con propina, consulta Reembolsar un pago.