> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trio.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Boleto FAQ

> Answers to the main questions integrators have about boletos at Trio: the embedded Pix QR code, payer data, statuses, webhooks, due date and expiration, refunds and installment books.

This page covers how boletos work at Trio: the hybrid boleto with Pix (BolePix), payer data, the status cycle, webhooks, due date and expiration, refunds and the issuance of installment books (carnês). It complements [Create a boleto](https://docs.trio.com.br/v2/guides/boleto/create-boleto.md) and the [Create boleto](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/post.md) API reference.

## BolePix

> **Does Trio's boleto have a Pix QR code?**
>
> Yes. Every boleto created by Trio also has an **embedded Pix QR code**, so the payer can choose between the traditional boleto payment and a payment via Pix.

> **Is the BR code returned when the boleto is created?**
>
> Not directly. When you create a boleto with [`POST /v2/in/boletos`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/post), the creation response does not include the Pix QR code hash.
>
> To get the Pix data, use the `id` returned in `data.id` and make a follow-up request:
>
> ```http theme={null}
> GET /v2/in/pix/qrcodes/{id}
> ```
>
> The BR code (the Pix copy-and-paste code) comes in `data.hash`. See the [Get dynamic QR code](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-dynamic/get.md) reference.

> **How do I identify if a boleto was paid via Pix?**
>
> When the boleto is paid through the embedded Pix QR code, the in document has `type` set to `pix_boleto`, which distinguishes it from a traditional boleto payment (`type: boleto`). The payment is sent through the `in_document` webhook with the same `type`:
>
> ```text theme={null}
> type: pix_boleto
> ```
>
> > [!TIP]
> >
> > Use the `type` field received in the webhook to identify the payment origin, and reconcile using the transaction identifiers.

## Payer data

> **Is the address provided in counterparty validated by Trio?**
>
> The address fills the fields the boleto schema requires, but Trio **does not validate whether the address belongs to the payer or corresponds to a real, existing address**. The address fields are `address`, `district`, `city`, `state` and `postal_code`.
>
> Even though the address is not validated, send real, accurate data whenever it is available.

## Boleto status

> **What are the main statuses of a boleto?**
>
> The boleto cycle follows Trio's document flow:
>
> ```text theme={null}
> created → confirmed → settled
> ```
>
> In addition to these states, a boleto moves to `expired` when it reaches its final payment deadline.
>
> | Status | Meaning |
> | - | - |
> | `created` | Boleto created |
> | `confirmed` | Boleto registered and confirmed |
> | `settled` | Boleto paid and settled |
> | `expired` | Boleto expired and can no longer be paid |
>
> The V2 status enum also defines `onhold`, `refunded`, `failed` and `cancelled`; a boleto canceled with [`POST /v2/in/boletos/{id}/cancel`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/cancel) is `cancelled`.

> **Which status indicates the boleto was paid?**
>
> `settled` indicates the boleto has been **paid and settled**. Do not treat `created` or `confirmed` alone as payment confirmation.

> **What happens when the boleto reaches expiration\_date?**
>
> When `expiration_date` is reached, the boleto moves to `expired` and no longer accepts payments.

## Webhooks

> **Which webhook reports a boleto payment?**
>
> The payment is communicated through the `in_document` webhook. When the boleto is paid via the Pix QR code, the `type` received is `pix_boleto`.

> **Does the external\_id provided at boleto creation appear in the webhook?**
>
> Yes. The `external_id` you send when creating the boleto is returned in the webhooks related to the document.
>
> Use `external_id` as the reference to your own system: it makes it easier to reconcile the transaction at Trio with the order or charge in your platform.

> **Is there a specific webhook for when the boleto becomes due?**
>
> No. Trio does not send an event just to report that the boleto reached its `due_date`. Handle that according to your own business needs. When the boleto reaches `expiration_date`, its status changes to `expired`.

> **Do I need to track boleto expiration in my system?**
>
> If your application needs to act when the boleto expires, yes. Since there is no dedicated expiration webhook, keep track of the dates in your system or query the boleto status with [`GET /v2/in/boletos/{id}`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/get) when needed.

## Due date and expiration

> **What is the difference between due\_date and expiration\_date?**
>
> The two fields represent different moments:
>
> * `due_date`: the boleto's due date.
> * `expiration_date`: the final date by which the boleto can still be paid.
>
> For example:
>
> ```text theme={null}
> due_date:        2026-09-10
> expiration_date: 2026-09-30
> ```
>
> Here the boleto is due on September 10 but can still be paid until September 30, as long as it is still valid.

> **Can I pay a boleto after its due\_date?**
>
> Yes. The boleto keeps accepting payments after the due date, as long as it has not reached `expiration_date`. After `due_date`, the charges configured for the boleto may apply, such as **interest and fines**.

> **What happens after expiration\_date?**
>
> After `expiration_date` the boleto becomes `expired` and can no longer be paid.

## Changing the due date

> **Can I change a boleto's due date?**
>
> Yes. Update the due date with [`PUT /v2/in/boletos/{id}`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/update), sending the new `due_detail.due_date`:
>
> ```http theme={null}
> PUT /v2/in/boletos/{id}
> ```
>
> The update returns `204 No Content`. Read the boleto back with [`GET /v2/in/boletos/{id}`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/get) to see the new `due_detail`.
>
> > [!NOTE]
> >
> > **Coming from V1?** `PUT /banking/cashin/boletos/{id}` returned the updated boleto. On V2 the update returns no body.

> **Does the barcode change when I update the due date?**
>
> No. Changing the due date updates `due_detail`, but the **barcode does not change**. The Pix QR code also stays the same.

> **Can I change the due date of an overdue boleto?**
>
> Yes. A boleto that has passed its `due_date` but has not expired yet can have its due date updated.

> **Can I change a boleto that has already expired?**
>
> No. A boleto with `expired` status cannot have its due date updated. If your operation allows renegotiation, make the update before the boleto reaches its `expiration_date`.

## Refunds and returns

> **Can I use the refund endpoint for a boleto?**
>
> It depends on how the boleto was paid. [`POST /v2/documents/in/{id}/refund`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/refunds/post) is intended for transactions originated via **Pix**:
>
> ```http theme={null}
> POST /v2/documents/in/{id}/refund
> ```
>
> So, if the boleto was paid using the **Pix QR code**, you can refund it with this endpoint.

> **How does a refund work when the boleto is paid via Pix?**
>
> The flow is:
>
> ```text theme={null}
> Boleto
>    ↓
> Pix QR code
>    ↓
> Pix payment
>    ↓
> Pix transaction (in document)
>    ↓
> POST /v2/documents/in/{id}/refund
> ```
>
> In this scenario the transaction originates from Pix, so the refund endpoint is available. The response returns the refund `id` in `data.in_refund_id`.

## Boleto URL

> **Does the boleto URL require authentication?**
>
> No. The `boleto_url` returned by the API is **public and does not require authentication** to access the document, so you can use the link directly in emails, checkouts, applications and order tracking pages. For example:
>
> ```text theme={null}
> https://receipts.sandbox.trio.com.br/0195aa08-7f58-51b9-79c4-cc88e7a150b1/boleto/01a05e1b-dced-0fa7-f252-0c3530c5f0e9
> ```
>
> Store the `boleto_url` along with the boleto data to make it easier to access the document later.

## Costs

> **Is there a charge for a boleto that was issued but not paid?**
>
> Confirm pricing and billing conditions directly with **Trio's sales team**. This matters especially for operations with a high issuance volume or installment books (carnês), where several installments may be generated in advance.

## Installment books (carnês) and batch issuance

> **Can I issue multiple boletos for the same purchase?**
>
> Yes. There is no additional limit on the number of boletos issued; the main restriction is the **rate limit of the creation endpoint**. This lets you, for example, create every installment of a carnê for the same purchase.

> **What is the rate limit for creating boletos?**
>
> The boleto creation endpoint has a standard rate limit of 60 requests per second. For batch issuance, organize your requests to respect this limit. See [Rate limit](https://docs.trio.com.br/v2/developers/rate-limit.md).

> **Does each boleto in a carnê need a different external\_id?**
>
> Yes. Each new boleto must have a unique `external_id`. For example:
>
> ```text theme={null}
> pedido-123-parcela-01
> pedido-123-parcela-02
> pedido-123-parcela-03
> ```
>
> This identifies each installment and avoids conflicts during reconciliation. Include a reference to the charge and to the installment in the `external_id`, so relating the boleto to the order in your system is simple.

## Integration best practices

> **What information should I store after creating a boleto?**
>
> Store, at minimum:
>
> * the boleto `id` at Trio (the same `id` identifies its embedded QR code);
> * `external_id`;
> * `due_date`;
> * `expiration_date`;
> * `boleto_url`.
>
> This information helps with **reconciliation, support, tracking and updating the charge**.

> **What should I consider when implementing boleto?**
>
> In summary:
>
> 1. **Consider both payment methods:** typeable line/barcode and Pix.
> 2. **Treat `settled` as a paid boleto.**
> 3. **Treat `expired` as a boleto that can no longer be paid.**
> 4. **Do not confuse `due_date` with `expiration_date`.**
> 5. **Track due date and expiration in your system when you need to trigger specific actions.**
> 6. **Use a unique `external_id` for each boleto.**
> 7. **Respect the rate limit of 60 requests per second.**
> 8. **Reconcile using the identifiers received in webhooks.**
> 9. **Store the `boleto_url` to make it easier to access the document.**
> 10. **Identify payments with `type = pix_boleto` when the boleto is paid via Pix.**

## Next steps

* [Create a boleto](https://docs.trio.com.br/v2/guides/boleto/create-boleto.md): the full request, with due date, discounts, fine and interest.
* [Boleto types](https://docs.trio.com.br/v2/guides/boleto/boleto-types.md): every invoice type and wallet type value.
* [Receivables](https://docs.trio.com.br/v2/guides/receivables/overview.md): every way to receive money on Trio.
* [Create boleto API reference](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/post.md): every field of the request and response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.