Skip to main content
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 and the Create boleto API reference.

​
BolePix

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.
Not directly. When you create a boleto with POST /v2/in/boletos, 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:
The BR code (the Pix copy-and-paste code) comes in data.hash. See the Get dynamic QR code reference.
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:
Use the type field received in the webhook to identify the payment origin, and reconcile using the transaction identifiers.

​
Payer data

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

The boleto cycle follows Trio’s document flow:
In addition to these states, a boleto moves to expired when it reaches its final payment deadline.The V2 status enum also defines onhold, refunded, failed and cancelled; a boleto canceled with POST /v2/in/boletos/{id}/cancel is cancelled.
settled indicates the boleto has been paid and settled. Do not treat created or confirmed alone as payment confirmation.
When expiration_date is reached, the boleto moves to expired and no longer accepts payments.

​
Webhooks

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.
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.
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.
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} when needed.

​
Due date and expiration

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:
Here the boleto is due on September 10 but can still be paid until September 30, as long as it is still valid.
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.
After expiration_date the boleto becomes expired and can no longer be paid.

​
Changing the due date

Yes. Update the due date with PUT /v2/in/boletos/{id}, sending the new due_detail.due_date:
The update returns 204 No Content. Read the boleto back with GET /v2/in/boletos/{id} to see the new due_detail.
Coming from V1? PUT /banking/cashin/boletos/{id} returned the updated boleto. On V2 the update returns no body.
No. Changing the due date updates due_detail, but the barcode does not change. The Pix QR code also stays the same.
Yes. A boleto that has passed its due_date but has not expired yet can have its due date updated.
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

It depends on how the boleto was paid. POST /v2/documents/in/{id}/refund is intended for transactions originated via Pix:
So, if the boleto was paid using the Pix QR code, you can refund it with this endpoint.
The flow is:
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

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:
Store the boleto_url along with the boleto data to make it easier to access the document later.

​
Costs

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

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.
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.
Yes. Each new boleto must have a unique external_id. For example:
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

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.
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