Create a boleto receivable by defining the charge, payer, payment conditions, and boleto configuration. This guide focuses on the request body and explains how each part of the boleto works, especially the payment rules such as discounts, fines, and interest.

All examples use fictitious data.

Request body

A boleto request is mainly composed of:

Boleto
│
├── Charge
│   ├── amount
│   ├── description
│   └── external_id
│
├── Payer
│   └── counterparty
│
├── Payment conditions
│   └── due_detail
│       ├── due_date
│       ├── discount
│       ├── fine
│       └── interest
│
├── Boleto configuration
│   ├── virtual_account_id
│   ├── expiration_date
│   ├── invoice_type
│   └── wallet_type
│
└── Optional
    ├── notes

The following example shows a complete boleto:

{
  "description": "Mensalidade agosto",
  "amount": 10000,
  "external_id": "boleto-demo-2026-001",
  "virtual_account_id": "019f0000-1234-5678-9abc-000000000001",
  "counterparty": {
    "name": "Maria Silva",
    "state": "SP",
    "address": "Rua das Flores, 100",
    "city": "Sao Paulo",
    "tax_number": "12345678901",
    "district": "Centro",
    "postal_code": "01001000"
  },
  "expiration_date": "2026-10-30",
  "invoice_type": "invoice",
  "wallet_type": "book_entry_electronic_bloquete",
  "notes": null,
  "due_detail": {
    "due_date": "2026-08-17",
    "fine": {
      "amount": 150,
      "calculation_type": "percentage"
    },
    "interest": {
      "amount": 300,
      "calculation_type": "monthly_fee"
    },
    "discount": {
      "fixed_until_due": {
        "amounts": [
          {
            "amount": 500,
            "date": "2026-08-16"
          }
        ],
        "calculation_type": "percentage"
      }
    }
  }
}

This example represents a R$ 100.00 boleto 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.

Charge

The charge section defines what is being collected and how your system identifies the boleto.

`amount`

Defines the boleto amount. The value is sent in cents.

"amount": 10000

means:

R$ 100.00

Examples:

→ R$ 15.00
→ R$ 100.00
 → R$ 4.02

This is the original amount of the boleto. Discounts, fines, and interest are payment conditions that can change the amount the customer must pay depending on when the boleto is paid.

`description`

A short description of the charge.

"description": "Mensalidade agosto"

Use it to identify what the customer is being charged for. For example:

Mensalidade agosto
Pedido 12345
Plano Premium
Serviço de consultoria

`external_id`

An identifier generated by your own system.

"external_id": "boleto-demo-2026-001"

It does not replace the Trio boleto ID. Instead, it allows your system to associate the boleto with an internal record. For example:

Your system
    │
    ├── Order: 12345
    ├── Invoice: 2026-08-001
    └── external_id: boleto-demo-2026-001
                              │
                              ▼
                         Trio boleto

This is particularly useful for reconciliation.

Payer

The counterparty object identifies the person or company that will pay the boleto.

"counterparty": {
  "name": "Maria Silva",
  "state": "SP",
  "address": "Rua das Flores, 100",
  "city": "Sao Paulo",
  "tax_number": "12345678901",
  "district": "Centro",
  "postal_code": "01001000"
}

The fields describe the payer:

Field	What it represents
`name`	Payer’s name
`tax_number`	CPF or CNPJ
`address`	Street and address number
`city`	Payer’s city
`state`	Brazilian state
`district`	Neighborhood
`postal_code`	CEP

The information should correspond to the actual payer associated with the boleto.

Payment conditions

The due_detail object is where the main payment rules are configured.

"due_detail": {
  "due_date": "2026-08-17",
  "discount": {},
  "fine": {},
  "interest": {}
}

It controls what happens before, on, and after the due date.

                 BOLETO

          Before due date
                 │
                 ▼
             Discount
                 │
                 ▼
             Due date
                 │
        ┌────────┴────────┐
        │                 │
      Payment          Late payment
                          │
                    ┌─────┴─────┐
                    ▼           ▼
                  Fine       Interest

Due date

`due_detail.due_date`

Defines the date on which the boleto becomes due.

"due_date": "2026-08-17"

In this example:

Due date = August 17, 2026

The due date is the reference point for the payment rules. Before this date, a discount may apply. After this date, the configured fine and interest may apply.

Discounts

A discount is a benefit given to the customer for paying before the due date. Discounts are configured inside:

"due_detail": {
  "discount": {}
}

The API supports two discount models:

fixed_until_due
per_day_antecipated

Fixed discount before the due date

Use fixed_until_due when you want to define a specific discount for one or more dates before the due date. Example:

"discount": {
  "fixed_until_due": {
    "amounts": [
      {
        "amount": 500,
        "date": "2026-08-16"
      }
    ],
    "calculation_type": "percentage"
  }
}

Here:

amount = 500
calculation_type = percentage

means 5%. For a R$ 100.00 boleto:

Original amount       R$ 100.00
Discount                    5%
Discount value         R$   5.00
Amount to pay          R$  95.00

The discount is available on the configured date.

Different discounts for different dates

You can define multiple discount dates:

"fixed_until_due": {
  "amounts": [
    {
      "amount": 500,
      "date": "2026-08-14"
    },
    {
      "amount": 300,
      "date": "2026-08-15"
    },
    {
      "amount": 100,
      "date": "2026-08-16"
    }
  ],
  "calculation_type": "percentage"
}

This represents:

Aug 14 → 5% discount
Aug 15 → 3% discount
Aug 16 → 1% discount
Aug 17 → Due date

This model is useful when the discount becomes smaller as the due date approaches.

Discount per anticipated day

The per_day_antecipated model calculates the discount based on how early the customer pays. Example:

"discount": {
  "per_day_antecipated": {
    "amount": 100,
    "calculation_days": "calendar",
    "calculation_type": "percentage"
  }
}

Here:

amount defines the discount value;
calculation_type defines whether the value is an amount or percentage;
calculation_days defines how days are counted.

The available day calculation modes are:

working
calendar

Use working for working days or calendar for calendar days.

Discount calculation type

The discount can be calculated as:

amount
percentage

Percentage

"calculation_type": "percentage"

The value represents a percentage. For example:

"amount": 500

means:

5%

Fixed amount

"calculation_type": "amount"

The value represents a monetary amount.

Fine

The fine is a penalty applied when the boleto is paid after the due date. It is configured with:

"fine": {
  "amount": 150,
  "calculation_type": "percentage"
}

There are two calculation types:

amount
percentage

Percentage fine

"amount": 150,
"calculation_type": "percentage"

represents a 1.5% fine. For a R$ 100.00 boleto:

Original amount: R$ 100.00
Fine:                 1.5%
Fine amount:      R$   1.50

Fixed fine

"amount": 150,
"calculation_type": "amount"

represents a fixed monetary fine. The important distinction is:

percentage → percentage of the boleto amount
amount     → fixed monetary value

Interest

Interest is another charge that can apply after the due date. It is configured with:

"interest": {
  "amount": 300,
  "calculation_type": "monthly_fee"
}

The available calculation types are:

daily_rate
monthly_fee
exempt
bank_control

Each type determines how the interest value is interpreted.

Daily interest

"interest": {
  "amount": 10,
  "calculation_type": "daily_rate"
}

The interest is configured as a daily rate.

Monthly interest

"interest": {
  "amount": 300,
  "calculation_type": "monthly_fee"
}

Here:

300 + monthly_fee

represents 3% per month. For a R$ 100.00 boleto, the configured monthly interest rate is:

3% per month

Exempt from interest

"interest": {
  "amount": 0,
  "calculation_type": "exempt"
}

Indicates that interest is exempt.

Bank-controlled interest

"interest": {
  "amount": 0,
  "calculation_type": "bank_control"
}

The interest calculation follows the bank-controlled configuration.

Fine vs. interest

Fine and interest are different concepts.

Fine

A penalty for paying after the due date.

Late payment
     │
     └── Fine

Interest

A charge related to the period the payment remains overdue.

Late payment
     │
     └── Interest
          │
          └── Based on the configured rate

They can be configured together. For example:

"fine": {
  "amount": 150,
  "calculation_type": "percentage"
},
"interest": {
  "amount": 300,
  "calculation_type": "monthly_fee"
}

means:

Fine     → 1.5%
Interest → 3% monthly

Boleto expiration

`expiration_date`

Defines the boleto expiration date.

"expiration_date": "2026-10-30"

This should be understood separately from the due date.

due_date
    │
    └── Payment due date

expiration_date
    │
    └── Boleto expiration

For example:

"due_detail": {
  "due_date": "2026-08-17"
},
"expiration_date": "2026-10-30"

The boleto is due on August 17, while its expiration is October 30.

Receiving account

`virtual_account_id`

Identifies the virtual account associated with the boleto.

"virtual_account_id": "019f0000-1234-5678-9abc-000000000001"

This is the virtual account that is associated with the boleto receivable. Always make sure the selected virtual account is the account intended to receive the payment.

Boleto type

The request contains two fields that define the boleto configuration:

"invoice_type": "invoice",
"wallet_type": "book_entry_electronic_bloquete"

These fields determine the type of document and wallet used for the boleto. Because there are multiple possible values and the correct combination depends on the boleto use case, the complete explanation is maintained in a dedicated guide. For details about invoice_type and wallet_type, open the Boleto Types guide. There you can find:

available invoice_type values;
available wallet_type values;
what each option represents;
when each type should be used;
examples of different boleto configurations.

Notes

`notes`

Optional additional information associated with the boleto. Example:

"notes": [
  "Customer reference",
  "Monthly subscription"
]

If there are no notes:

"notes": null

Use notes for additional information that does not need to be part of the main charge description.

Example: complete payment configuration

Suppose you want to create a boleto with:

Amount:              R$ 100.00
Due date:            17/08/2026
Discount:             5% until 16/08/2026
Fine after due date:  1.5%
Interest:             3% monthly

The payment rules are:

"due_detail": {
  "due_date": "2026-08-17",
  "discount": {
    "fixed_until_due": {
      "amounts": [
        {
          "amount": 500,
          "date": "2026-08-16"
        }
      ],
      "calculation_type": "percentage"
    }
  },
  "fine": {
    "amount": 150,
    "calculation_type": "percentage"
  },
  "interest": {
    "amount": 300,
    "calculation_type": "monthly_fee"
  }
}

The resulting behavior can be understood as:

                    R$ 100.00
                         │
             ┌───────────┴───────────┐
             │                       │
       Pay before due            Pay after due
             │                       │
        5% discount             1.5% fine
             │                  + 3% monthly
             │                     interest
             ▼                       ▼
        R$ 95.00*              Updated amount

* Assuming the 5% discount applies on the payment date and no other charge applies.

Complete request example

{
  "description": "Mensalidade agosto",
  "amount": 10000,
  "external_id": "boleto-demo-2026-001",
  "virtual_account_id": "019f0000-1234-5678-9abc-000000000001",
  "counterparty": {
    "name": "Maria Silva",
    "state": "SP",
    "address": "Rua das Flores, 100",
    "city": "Sao Paulo",
    "tax_number": "12345678901",
    "district": "Centro",
    "postal_code": "01001000"
  },
  "expiration_date": "2026-10-30",
  "invoice_type": "invoice",
  "wallet_type": "book_entry_electronic_bloquete",
  "notes": null,
  "due_detail": {
    "due_date": "2026-08-17",
    "fine": {
      "amount": 150,
      "calculation_type": "percentage"
    },
    "interest": {
      "amount": 300,
      "calculation_type": "monthly_fee"
    },
    "discount": {
      "fixed_until_due": {
        "amounts": [
          {
            "amount": 500,
            "date": "2026-08-16"
          }
        ],
        "calculation_type": "percentage"
      }
    }
  }
}

In this request:

Field	Meaning
`amount`	Original boleto value: R$ 100.00
`description`	Description of the charge
`external_id`	Internal reference from the client system
`virtual_account_id`	Virtual account associated with the receivable
`counterparty`	Payer information
`due_date`	Payment due date
`discount`	Early-payment benefit
`fine`	Late-payment penalty
`interest`	Late-payment interest
`expiration_date`	Boleto expiration
`invoice_type`	Document type
`wallet_type`	Boleto wallet configuration
`notes`	Optional additional information

For more information about the document and wallet configuration, see the Boleto Types guide.

​Request body

​Charge

​amount

​description

​external_id

​Payer

​Payment conditions

​Due date

​due_detail.due_date

​Discounts

​Fixed discount before the due date

​Different discounts for different dates

​Discount per anticipated day

​Discount calculation type

​Percentage

​Fixed amount

​Fine

​Percentage fine

​Fixed fine

​Interest

​Daily interest

​Monthly interest

​Exempt from interest

​Bank-controlled interest

​Fine vs. interest

​Fine

​Interest

​Boleto expiration

​expiration_date

​Receiving account

​virtual_account_id

​Boleto type

​Notes

​notes

​Example: complete payment configuration

​Complete request example

Request body

Charge

`amount`

`description`

`external_id`

Payer

Payment conditions

Due date

`due_detail.due_date`

Discounts

Fixed discount before the due date

Different discounts for different dates

Discount per anticipated day

Discount calculation type

Percentage

Fixed amount

Fine

Percentage fine

Fixed fine

Interest

Daily interest

Monthly interest

Exempt from interest

Bank-controlled interest

Fine vs. interest

Fine

Interest

Boleto expiration

`expiration_date`

Receiving account

`virtual_account_id`

Boleto type

Notes

`notes`

Example: complete payment configuration

Complete request example