--- title: "Invoice at the time of payment | Timbro" description: "Timbro issues the invoice when the customer pays, or your system issues it and links it to the payment" canonical: "https://timbro.do/en/docs/comprobantes/emitir-ecf/" --- 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](https://timbro.do/en/docs/comprobantes/cobrar-una-factura/). 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](https://timbro.do/en/docs/comprobantes/configurar-facturacion/) 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 Send the items and, in `invoicing`, the `automatic` mode and the document type Checkout shows as selected when it opens: - [TypeScript](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-0-0) - [Python](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-0-1) ```ts 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" }, }); ``` ```python import os from timbro_invoices import TimbroInvoices from timbro_payments import TimbroPayments timbro = TimbroPayments(api_key=os.environ["TIMBRO_API_KEY"]) timbro_invoices = TimbroInvoices(api_key=os.environ["TIMBRO_API_KEY"]) automatic_payment = 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: - [TypeScript](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-1-0) - [Python](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-1-1) ```ts const paid = await timbro.payments.retrieve(automaticPayment.id); const invoice = paid.invoiceId ? await timbroInvoices.invoices.retrieve(paid.invoiceId) : undefined; ``` ```python paid = timbro.payments.retrieve(automatic_payment["id"]) invoice = timbro_invoices.invoices.retrieve(paid["invoiceId"]) if paid["invoiceId"] else None ``` The guide [Download and send the invoice](https://timbro.do/en/docs/comprobantes/entregar-comprobante/) explains the invoice statuses and how to download the XML and the PDF. ## 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](https://timbro.do/en/docs/comprobantes/facturar-desde-pos-erp/) when the payment is confirmed, and then links it to the payment. First create the payment and store its `id` with the sale: - [TypeScript](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-2-0) - [Python](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-2-1) ```ts 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" }, }); ``` ```python merchant_payment = 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: - [TypeScript](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-3-0) - [Python](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-3-1) ```ts 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", }); ``` ```python current_payment = timbro.payments.retrieve(merchant_payment["id"]) if current_payment["status"] != "succeeded": raise RuntimeError("Payment not yet confirmed") linked = timbro.payments.attach_invoice( merchant_payment["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 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`: - [TypeScript](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-4-0) - [Python](https://timbro.do/en/docs/comprobantes/emitir-ecf/#tab-panel-4-1) ```ts await timbro.payments.updateInvoiceRecipient({ paymentId: automaticPayment.id, recipientEmail: "buyer@example.com", idempotencyKey: "sale-124-email-1", }); ``` ```python timbro.payments.update_invoice_recipient( automatic_payment["id"], {"recipientEmail": "buyer@example.com"}, idempotency_key="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](https://timbro.do/en/docs/comprobantes/entregar-comprobante/#email-the-invoice). ## 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](https://timbro.do/en/docs/comprobantes/configurar-facturacion/#switch-to-live-mode) 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. [Previous\ Collect an invoice you already issued](https://timbro.do/en/docs/comprobantes/cobrar-una-factura/)[Next\ Retrieve and cancel payments](https://timbro.do/en/docs/cobros/consultar-pagos/) Sell, serve your customers, and collect payments from your phone © 2026 Timbro. All rights reserved [Español](https://timbro.do/docs/comprobantes/emitir-ecf/)[English](https://timbro.do/en/docs/comprobantes/emitir-ecf/) ## 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/) ## 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/)