Skip to content
Documentation
Get started

Collect and invoice

Invoice at the time of payment

If your customer pays online and your system does not issue invoices, Timbro can issue the invoice as soon as the payment is confirmed. In Checkout, your customer can choose whether they want a Consumer Invoice or a Tax Credit Invoice and enter their RNC; Timbro issues the invoice with the payment’s items.

If your system already issues the invoice before collecting, you do not need this guide: collect the invoice you already issued.

To invoice when you create the payment, you need:

  • An API key with Collect and Invoicing access. These examples store it in TIMBRO_API_KEY.
  • Invoicing set up in the mode you will use.
  • The sale’s items, in Dominican pesos (DOP), with their unit of measure (unit) and whether each is a good or a service (kind). A payment that only carries amount cannot be invoiced.

Timbro issues the invoice

Section titled “Timbro issues the invoice”

Send the items and, in invoicing, the automatic mode and the document type Checkout shows as selected when it opens:

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


const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_API_KEY! });
const timbroInvoices = createTimbroInvoices({ apiKey: process.env.TIMBRO_API_KEY! });
const automaticPayment = await timbro.payments.create({
  paymentReference: "sale-124",
  currency: "DOP",
  items: [{
    description: "Service",
    quantity: "1",
    unit: "unit",
    kind: "service",
    unitPrice: "1250.00",
    tax: { kind: "itbis_18", included: true },
  }],
  returnUrl: "https://merchant.example/sales/124",
  invoicing: { mode: "automatic", type: "E32", recipientEmail: "buyer@example.com" },
});

type can be Consumer Invoice (E32), Tax Credit Invoice (E31), or Government Invoice (E45). The customer can change it in Checkout. To limit the types they can choose, send allowedTypes; to stop them from changing it, send isTypeLocked: true. If you already know the buyer, send them in buyer, and isBuyerLocked: true stops the customer from changing it. A Government Invoice also needs governmentEligibility.

recipientEmail is optional. With it, Timbro emails the invoice to the customer when the DGII accepts it.

When the payment reaches succeeded, Timbro issues the invoice and the payment shows its invoiceId. Retrieve the invoice to learn its status and files; a payment in succeeded does not confirm that the DGII has accepted the invoice:

const paid = await timbro.payments.retrieve(automaticPayment.id);
const invoice = paid.invoiceId ? await timbroInvoices.invoices.retrieve(paid.invoiceId) : undefined;

The guide Download and send the invoice explains the invoice statuses and how to download the XML and the PDF.

When your system issues the invoice after the payment

Section titled “When your system issues the invoice after the payment”

If your system must issue the invoice, but you want the customer to choose the document type in Checkout, create the payment with the merchant mode. Timbro stores the customer’s choice and does not issue the invoice; your system issues it with the invoicing API when the payment is confirmed, and then links it to the payment.

First create the payment and store its id with the sale:

const merchantPayment = await timbro.payments.create({
  paymentReference: "sale-125",
  currency: "DOP",
  items: [{
    description: "Service",
    quantity: "1",
    unit: "unit",
    kind: "service",
    unitPrice: "1250.00",
    tax: { kind: "itbis_18", included: true },
  }],
  invoicing: { mode: "merchant", type: "E32" },
});

When the payment is in succeeded, read in invoicing the type and buyer the customer chose, issue the invoice with that data and the same items, and wait for the DGII to accept it. Then link it to the payment:

const currentPayment = await timbro.payments.retrieve(merchantPayment.id);
if (currentPayment.status !== "succeeded") throw new Error("Payment not yet confirmed");
const linked = await timbro.payments.attachInvoice(merchantPayment.id, {
  invoiceId: "f35b7ae4-c484-4c63-981e-4f0f15e913b5",
});

The invoice must belong to the same business and the same mode as the payment, and its fiscal data must match the sale. If they do not match, the API rejects the link and the invoice stays valid with the DGII.

Change the invoice email

Section titled “Change the invoice email”

The payment shows in invoicing.recipientEmail the email Timbro will send the invoice to, or null if there is none. To change it before it is sent, use PUT /v1/payments/{paymentId}/invoice-recipient:

await timbro.payments.updateInvoiceRecipient({
  paymentId: automaticPayment.id,
  recipientEmail: "buyer@example.com",
  idempotencyKey: "sale-124-email-1",
});

Timbro or your system emails the invoice to the customer, never both. If your system sends it, do not set recipientEmail or call this operation. To email an invoice that already exists, follow Email the invoice.

Invoice in Live mode

Section titled “Invoice in Live mode”

In Live mode, Timbro only accepts a payment with automatic or merchant when your business can already issue Live every type the payment allows. If something is missing, the API responds 409 business_fiscal_setup_incomplete, and its detail says what is missing; Set up invoicing explains how to complete it. If Timbro cannot check it at that moment, it responds 503 business_fiscal_setup_unavailable: repeat the same request later.

A payment without an invoice, or a payment for an invoice that already exists, does not need this check. That is why a point-of-sale system that issues its own invoices can keep collecting even when Timbro invoicing is unavailable.