Taxes and items

Send amounts as decimal strings, for example "1250.00". The payment total already includes tax: Timbro does not add it again or assume a rate when it is missing.

Configure the usual tax

If all your payments use the same rate and prices already include it, configure a default once per merchant and mode. This call uses an administrator key:

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,
});

You can also use itbis_16, zero_rated, or exempt. The call keeps the other Checkout options. If you get a revision conflict, retrieve the policy again before updating it.

After that, you can create a payment without sending tax. Mixed-tax payments or additional fees need an explicit tax or items.

Declare tax on a payment

Add tax: { includedAmount: "190.68" } to a DOP payment for "1250.00" to declare the included tax portion. This value replaces the default. Use "0.00" when the included tax is zero.

Without an explicit tax or an applicable default, the payment is rejected for missing data.

Collect with items

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

This example collects RD$ 236.00, including RD$ 36.00 in ITBIS. You can combine items with different tax treatments. Omitting quantity means one.

Timbro calculates the totals with the rules in the next section. If your ERP already computed them, add expectedTotals: they must match to the cent. Each item’s fiscal fields become required when you request an e-CF; the exact fields are in the REST reference.

How totals are rounded

Timbro multiplies each item’s quantity by its price without rounding. It then groups items by rate and by whether the price includes ITBIS, and rounds each group once to the cent. An exact half cent rounds up.

Group	Base	ITBIS
Prices including ITBIS	The rounded total minus the ITBIS	The sum × 18/118 (or 16/116), rounded
Prices excluding ITBIS	The rounded sum	18% (or 16%) of the sum, rounded
Zero-rated or exempt	The rounded sum	Not applicable

For example, at the 18% rate:

• A price of 100.00 with ITBIS included gives a base of 84.75, ITBIS of 15.25, and a total of 100.00.
• Two prices excluding ITBIS, 10.01 and 10.02, give a base of 20.03, ITBIS of 3.61, and a total of 23.64.

With prices that include ITBIS, the group total is always the rounded sum of its prices. Each rate’s amounts are the sum of its groups.

The legal tip is 10% of the items with legalTip: { applied: true }, each without its included ITBIS: a price including 18% ITBIS is divided by 1.18, and one including 16% by 1.16. Prices without ITBIS, zero-rated prices, and exempt prices count in full. The tip is rounded once for the whole sale.

The customer pays the bases, exempt amounts, ITBIS, legal tip, and non-billable charges. These are the same figures as the e-CF.

Offer a voluntary tip

A payment offers a voluntary tip only when the sale includes an item with a legal tip and checkoutPreferences.tips is enabled. If either is missing, the API returns 422 merchant_checkout_policy_invalid at /checkoutPreferences.

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

This example collects RD$ 1,084.75: RD$ 1,000.00 for the meal and RD$ 84.75 in legal tip, 10% of 1000.00 / 1.18. Any voluntary tip the customer chooses is added to that total.

To refund a payment with a tip, see Refund a payment.