Choose how to integrate your system

Your system can collect with Timbro, issue e-invoices with Timbro, or do both. The payment and the invoice are separate resources, and each guide in this documentation starts from a specific sales situation. Find the one in the table that looks like your business and open its guide.

Business situation	What your system does
Your system issues the invoice and the customer pays later, with a payment link or a QR	Issues the invoice and creates a payment with its invoiceId
A credit sale that the customer pays in partial payments	Issues the invoice with credit terms and creates one payment for each partial payment
The customer pays online and Timbro issues the invoice when the payment is confirmed	Creates the payment with the sale’s items and the document type
The customer pays first and your system issues the invoice afterward	Creates the payment, then links the invoice you issued to it
Your system invoices and the customer pays outside Timbro: in cash, by transfer, or on the card terminal	Issues the invoice and states on it how the customer paid
You only need to collect, with no invoice	Creates an amount-based payment
You return money for a sale you already invoiced	Creates the refund, issues the credit note, and links them

Invoicing does not require an Azul, CardNet, or Portal merchant account. Collecting by card does. You can do both with the same API key if you give it Collect and Invoicing access.

What your system stores

Each sale can have a payment, an invoice, or both. Store these values with the sale so you can retrieve each resource and repeat a request without duplicating it:

Value	What it is for
paymentReference	Your system sets it to identify the payment. If you repeat the request with the same reference, you get the same payment
Payment id	Timbro assigns it. Use it to retrieve, cancel, or refund the payment
invoiceReference	Your system sets it to identify the invoice. If you repeat the request with the same reference, you get the same invoice
invoiceId	Timbro assigns it. Use it to retrieve the invoice, download its files, and collect it
e-NCF	Timbro assigns it. It is the fiscal number you print; your system does not calculate it

A payment in succeeded confirms that the customer paid, but not that the DGII accepted the invoice or that its PDF is ready. Retrieve each resource separately.

How your system learns about a change

Timbro notifies your server with a webhook when a payment, a refund, or an invoice changes. The notification only says what changed; your server then retrieves the resource to learn its current status. If your server cannot receive notifications, poll the payments and invoices that are still pending.