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

# Create Boleto

> Guide to create boleto

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:

```text theme={null}
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:

```json theme={null}
{
  "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**.

```json theme={null}
"amount": 10000
```

means:

```text theme={null}
R$ 100.00
```

Examples:

```text theme={null}
1500  → R$ 15.00
10000 → R$ 100.00
402   → 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.

```json theme={null}
"description": "Mensalidade agosto"
```

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

For example:

```text theme={null}
Mensalidade agosto
Pedido 12345
Plano Premium
Serviço de consultoria
```

***

## `external_id`

An identifier generated by your own system.

```json theme={null}
"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:

```text theme={null}
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.

```json theme={null}
"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.

```json theme={null}
"due_detail": {
  "due_date": "2026-08-17",
  "discount": {},
  "fine": {},
  "interest": {}
}
```

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

```text theme={null}
                 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.

```json theme={null}
"due_date": "2026-08-17"
```

In this example:

```text theme={null}
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:

```json theme={null}
"due_detail": {
  "discount": {}
}
```

The API supports two discount models:

```text theme={null}
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:

```json theme={null}
"discount": {
  "fixed_until_due": {
    "amounts": [
      {
        "amount": 500,
        "date": "2026-08-16"
      }
    ],
    "calculation_type": "percentage"
  }
}
```

Here:

```text theme={null}
amount = 500
calculation_type = percentage
```

means **5%**.

For a R\$ 100.00 boleto:

```text theme={null}
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:

```json theme={null}
"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:

```text theme={null}
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:

```json theme={null}
"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:

```text theme={null}
working
calendar
```

Use `working` for working days or `calendar` for calendar days.

***

## Discount calculation type

The discount can be calculated as:

```text theme={null}
amount
percentage
```

### Percentage

```json theme={null}
"calculation_type": "percentage"
```

The value represents a percentage.

For example:

```json theme={null}
"amount": 500
```

means:

```text theme={null}
5%
```

### Fixed amount

```json theme={null}
"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:

```json theme={null}
"fine": {
  "amount": 150,
  "calculation_type": "percentage"
}
```

There are two calculation types:

```text theme={null}
amount
percentage
```

## Percentage fine

```json theme={null}
"amount": 150,
"calculation_type": "percentage"
```

represents a **1.5% fine**.

For a R\$ 100.00 boleto:

```text theme={null}
Original amount: R$ 100.00
Fine:                 1.5%
Fine amount:      R$   1.50
```

## Fixed fine

```json theme={null}
"amount": 150,
"calculation_type": "amount"
```

represents a fixed monetary fine.

The important distinction is:

```text theme={null}
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:

```json theme={null}
"interest": {
  "amount": 300,
  "calculation_type": "monthly_fee"
}
```

The available calculation types are:

```text theme={null}
daily_rate
monthly_fee
exempt
bank_control
```

Each type determines how the interest value is interpreted.

## Daily interest

```json theme={null}
"interest": {
  "amount": 10,
  "calculation_type": "daily_rate"
}
```

The interest is configured as a daily rate.

## Monthly interest

```json theme={null}
"interest": {
  "amount": 300,
  "calculation_type": "monthly_fee"
}
```

Here:

```text theme={null}
300 + monthly_fee
```

represents **3% per month**.

For a R\$ 100.00 boleto, the configured monthly interest rate is:

```text theme={null}
3% per month
```

## Exempt from interest

```json theme={null}
"interest": {
  "amount": 0,
  "calculation_type": "exempt"
}
```

Indicates that interest is exempt.

## Bank-controlled interest

```json theme={null}
"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.

```text theme={null}
Late payment
     │
     └── Fine
```

### Interest

A charge related to the period the payment remains overdue.

```text theme={null}
Late payment
     │
     └── Interest
          │
          └── Based on the configured rate
```

They can be configured together.

For example:

```json theme={null}
"fine": {
  "amount": 150,
  "calculation_type": "percentage"
},
"interest": {
  "amount": 300,
  "calculation_type": "monthly_fee"
}
```

means:

```text theme={null}
Fine     → 1.5%
Interest → 3% monthly
```

# Boleto expiration

## `expiration_date`

Defines the boleto expiration date.

```json theme={null}
"expiration_date": "2026-10-30"
```

This should be understood separately from the due date.

```text theme={null}
due_date
    │
    └── Payment due date

expiration_date
    │
    └── Boleto expiration
```

For example:

```json theme={null}
"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.

```json theme={null}
"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:

```json theme={null}
"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](/guides/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:

```json theme={null}
"notes": [
  "Customer reference",
  "Monthly subscription"
]
```

If there are no notes:

```json theme={null}
"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:

```text theme={null}
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:

```json theme={null}
"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:

```text theme={null}
                    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

```json theme={null}
{
  "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](/guides/boleto-types) guide.