Skip to main content
This guide walks through the request body of POST /v2/in/boletos: the charge, the payer, the payment rules (discounts, fines and interest) and the boleto configuration. It then shows the response and what you can do with the boleto after creation. The complete field list is in the Create boleto API reference. All examples use fictitious data and the sandbox base URL https://api.sandbox.trio.com.br.

​
What you need

  • The id of the bank account that receives the payment. List your accounts with List bank accounts.
  • The payer’s name, CPF or CNPJ and full address. Trio needs them to fill in the boleto document.
  • An invoice_type and a wallet_type. The Boleto types guide lists the values and the default wallet type.
  • Optionally, split recipients and a fee. See Split payments and Fees.

​
Request body overview

A boleto request has four parts, plus a few optional fields:
The following request creates a complete boleto:
This example is a boleto of BRL 100.00 with:
  • due date on August 17, 2026;
  • 5% discount until August 16;
  • 1.5% fine after the due date;
  • 3% monthly interest after the due date.
Amounts are in cents (BRL 100.00 = 10000). Every payment rule inside due_detail follows the same convention: a rule calculated as a monetary amount sends amount in cents, and a rule calculated as a percentage sends value in basis points (100 = 1%). The sections below show both forms for each rule.
Coming from V1? In V1 the percentage of a rule was also sent in amount. In V2 percentages move to value; the numbers themselves do not change (500 was and still is 5%).

​
Charge

The charge says what you are collecting and how your system identifies the boleto.

​
Payer

The counterparty object identifies the person or company that pays the boleto.
Send the data of the actual payer: Trio does not validate the address, but it goes on the boleto document. In the response, the payer comes back as a counterparty object with the id Trio assigned to it. The Boleto best practices guide explains what is and is not validated.

​
Payment conditions

The due_detail object holds the due date and the rules that apply before and after it.
In the response, discount, fine and interest are present only when you set them.

​
Due date

Before this date a discount may apply. After it, the configured fine and interest may apply.

​
Discount

A discount rewards the payer for paying before the due date. The API supports two models; set only one of them in a boleto. Fixed discount until a date. The discount applies until the configured date, which is the last day on which it is valid:
Here value = 500 with calculation_type = percentage means 5%. For a BRL 100.00 boleto:
Different discounts for different dates. Add one entry per date when the discount shrinks as the due date approaches:
Discount per anticipated day. The per_day_antecipated model calculates the discount from how early the payer pays:
Calculation type. Both discount models, and the fine, read the same two calculation types:

​
Fine

The fine is a penalty applied when the boleto is paid after the due date.
For a BRL 100.00 boleto with a 1.5% fine:

​
Interest

Interest is a second charge that can apply after the due date.
The calculation type determines how the interest is interpreted and which field carries it: Daily interest, here BRL 0.10 per day overdue:
Monthly interest, here 3% per month:
Exempt from interest:
Bank-controlled interest:

​
Fine and interest together

Fine and interest are different concepts: the fine is a one-time penalty for paying late, while interest depends on how long the payment stays overdue and on the configured rate. You can configure both on the same boleto:
This means a 1.5% fine plus 3% monthly interest.

​
Putting the rules together

Suppose you want a boleto with:
The payment rules are:
The resulting behavior:
* Assuming the 5% discount applies on the payment date and no other charge applies.

​
Boleto configuration

These fields tell Trio which account receives the payment, how long the boleto stays payable and how the bank registers it.

​
Due date versus expiration date

due_date is when the boleto becomes due; from that day the fine and interest apply. expiration_date is the last day the boleto can be paid at all. A boleto can be paid after its due date as long as the expiration date has not passed.
This boleto is due on August 17 and can be paid until October 30. The Boleto best practices guide covers how each date affects updates and what happens after expiration.

​
Notes

​
Splits, fee and merchant

All three are optional.

​
Splits

splits distributes the payment of the boleto among split recipients. Each item names a counterparty_recipient_id, a type (percentage or fixed) and a value (a percentage from 0 to 100, or a fixed amount in cents).
The Split payments guide explains how recipients are created and how the amounts are distributed.

​
Fee

options.fee is the fee charged on the payment of the boleto, in cents. The response returns it as a money object.
The Fees guide explains how the fee is settled.

​
Merchant

merchant is the merchant to register as the split org merchant. When sent, it is saved.

​
Response

A successful request returns 201 Created with the boleto under data:
The fields worth keeping in your system: A rule configured with calculation_type: amount is returned with its amount as a money object:

​
After creation

Every boleto is hybrid: the same id identifies its embedded Pix QR code, which you read with GET /v2/in/pix/qrcodes/{id}. Payments reach you as webhook events; the events overview lists them, and the Boleto best practices guide covers the hybrid boleto, its lifecycle and reconciliation. The boleto itself is managed through these endpoints: To change the due date:
To change the amount, recreate the boleto:
A boleto paid through its Pix QR code can be refunded with Refund a receivable (POST /v2/documents/in/{id}/refund), where {id} is the in document of the payment, not the boleto. The best practices guide explains when a refund applies.

​
Next steps