> ## 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 a boleto

> Build the request body of POST /v2/in/boletos, from the charge and payer to discounts, fines, interest and splits, and read the boleto that comes back.

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](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/post.md) 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](https://docs.trio.com.br/v2/api-reference/banking-api/bank-accounts/list-bank-accounts.md).
* 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](https://docs.trio.com.br/v2/guides/boleto/boleto-types.md) guide lists the values and the default wallet type.
* Optionally, split recipients and a fee. See [Split payments](https://docs.trio.com.br/v2/guides/receivables/split-payments.md) and [Fees](https://docs.trio.com.br/v2/guides/receivables/fees.md).

## Request body overview

```http theme={null}
POST /v2/in/boletos
```

A boleto request has four parts, plus a few optional fields:

```text theme={null}
Boleto
│
├── Charge
│   ├── amount
│   ├── description
│   └── external_id
│
├── Payer
│   └── counterparty
│
├── Payment conditions
│   └── due_detail
│       ├── due_date
│       ├── discount
│       ├── fine
│       └── interest
│
├── Boleto configuration
│   ├── bank_account_id
│   ├── expiration_date
│   ├── invoice_type
│   └── wallet_type
│
└── Optional
    ├── notes
    ├── splits
    ├── options
    └── merchant
```

The following request creates a complete boleto:

```json theme={null}
{
  "description": "Mensalidade agosto",
  "amount": 10000,
  "external_id": "boleto-demo-2026-001",
  "bank_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": {
      "value": 150,
      "calculation_type": "percentage"
    },
    "interest": {
      "value": 300,
      "calculation_type": "monthly_fee"
    },
    "discount": {
      "fixed_until_due": {
        "amounts": [
          {
            "value": 500,
            "date": "2026-08-16"
          }
        ],
        "calculation_type": "percentage"
      }
    }
  }
}
```

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.

> [!NOTE]
>
> **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.

```json theme={null}
"amount": 10000,
"description": "Mensalidade agosto",
"external_id": "boleto-demo-2026-001"
```

| Field | Required | Description |
| - | - | - |
| `amount` | Yes | Boleto amount in cents. This is the original amount: discounts, fines and interest change what the payer owes depending on when they pay. It cannot be changed after creation; to charge a different amount, [recreate the boleto](#after-creation). |
| `description` | No | Short description of the charge, up to 25 characters, such as `Mensalidade agosto`, `Pedido 12345` or `Plano Premium`. |
| `external_id` | No | Identifier generated by your own system, up to 40 characters. It does not replace the Trio boleto `id`; it ties the boleto to an internal record (an order, an invoice, an installment), which makes reconciliation easier. |

## Payer

The `counterparty` object identifies the person or company that pays 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"
}
```

| Field | Required | Description |
| - | - | - |
| `name` | Yes | Payer's name |
| `tax_number` | Yes | CPF or CNPJ, digits only (11 to 14 digits) |
| `address` | Yes | Street and number |
| `city` | Yes | Payer's city |
| `state` | Yes | Brazilian state as a two-letter code (`SP`) |
| `district` | Yes | Neighborhood |
| `postal_code` | Yes | CEP, 8 digits with no separator |

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](https://docs.trio.com.br/v2/guides/boleto/best-practices.md) 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.

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

| Field | Required | Description |
| - | - | - |
| `due_date` | Yes | Date on which the boleto becomes due. It is the reference point for every other rule. |
| `discount` | No | Benefit for paying before the due date. |
| `fine` | No | One-time penalty for paying after the due date. |
| `interest` | No | Charge that grows with the time the payment stays overdue. |

```text theme={null}
                 BOLETO

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

In the response, `discount`, `fine` and `interest` are present only when you set them.

### Due date

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

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.

| Model | Use it when |
| - | - |
| `fixed_until_due` | You want a specific discount for one or more dates before the due date. |
| `per_day_antecipated` | You want the discount to grow with each day the payer anticipates. |

**Fixed discount until a date.** The discount applies until the configured date, which is the last day on which it is valid:

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

Here `value = 500` with `calculation_type = percentage` means 5%. For a BRL 100.00 boleto:

```text theme={null}
Original amount       BRL 100.00
Discount                     5%
Discount value         BRL   5.00
Amount to pay          BRL  95.00
```

**Different discounts for different dates.** Add one entry per date when the discount shrinks as the due date approaches:

```json theme={null}
"fixed_until_due": {
  "amounts": [
    {
      "value": 500,
      "date": "2026-08-14"
    },
    {
      "value": 300,
      "date": "2026-08-15"
    },
    {
      "value": 100,
      "date": "2026-08-16"
    }
  ],
  "calculation_type": "percentage"
}
```

```text theme={null}
Aug 14 → 5% discount
Aug 15 → 3% discount
Aug 16 → 1% discount
Aug 17 → Due date
```

**Discount per anticipated day.** The `per_day_antecipated` model calculates the discount from how early the payer pays:

```json theme={null}
"discount": {
  "per_day_antecipated": {
    "value": 100,
    "calculation_days": "calendar",
    "calculation_type": "percentage"
  }
}
```

| Field | Description |
| - | - |
| `value` or `amount` | Discount granted per day paid in advance. Which field you send depends on `calculation_type`. |
| `calculation_type` | `percentage` or `amount`. |
| `calculation_days` | How days are counted: `working` for working days or `calendar` for calendar days. |

**Calculation type.** Both discount models, and the fine, read the same two calculation types:

| `calculation_type` | Field it reads | Example |
| - | - | - |
| `percentage` | `value`, in basis points (100 = 1%) | `"value": 500` is 5% |
| `amount` | `amount`, in cents | `"amount": 500` is BRL 5.00 |

### Fine

The fine is a penalty applied when the boleto is paid after the due date.

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

| `calculation_type` | Fields | Meaning |
| - | - | - |
| `percentage` | `"value": 150` | 1.5% of the boleto amount, in basis points |
| `amount` | `"amount": 150` | Fixed fine of BRL 1.50, in cents |

For a BRL 100.00 boleto with a 1.5% fine:

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

### Interest

Interest is a second charge that can apply after the due date.

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

The calculation type determines how the interest is interpreted and which field carries it:

| `calculation_type` | Field it reads | Meaning |
| - | - | - |
| `daily_rate` | `amount`, in cents | Fixed amount charged per day overdue |
| `monthly_fee` | `value`, in basis points | Percentage charged per month |
| `exempt` | None | No interest. Do not send `amount` or `value`. |
| `bank_control` | None | The bank-controlled configuration applies. Do not send `amount` or `value`. |

Daily interest, here BRL 0.10 per day overdue:

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

Monthly interest, here 3% per month:

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

Exempt from interest:

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

Bank-controlled interest:

```json theme={null}
"interest": {
  "calculation_type": "bank_control"
}
```

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

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

This means a 1.5% fine plus 3% monthly interest.

### Putting the rules together

Suppose you want a boleto with:

```text theme={null}
Amount:              BRL 100.00
Due date:            2026-08-17
Discount:             5% until 2026-08-16
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": [
        {
          "value": 500,
          "date": "2026-08-16"
        }
      ],
      "calculation_type": "percentage"
    }
  },
  "fine": {
    "value": 150,
    "calculation_type": "percentage"
  },
  "interest": {
    "value": 300,
    "calculation_type": "monthly_fee"
  }
}
```

The resulting behavior:

```text theme={null}
                    BRL 100.00
                         │
             ┌───────────┴───────────┐
             │                       │
       Pay before due            Pay after due
             │                       │
        5% discount             1.5% fine
             │                  + 3% monthly
             │                     interest
             ▼                       ▼
        BRL 95.00*             Updated amount
```

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

```json theme={null}
"bank_account_id": "019f0000-1234-5678-9abc-000000000001",
"expiration_date": "2026-10-30",
"invoice_type": "invoice",
"wallet_type": "book_entry_electronic_bloquete",
"notes": null
```

| Field | Required | Description |
| - | - | - |
| `bank_account_id` | Yes | Bank account the boleto is issued against and that is credited when it is paid. Make sure it is the account meant to receive the payment. |
| `expiration_date` | Yes | Last day on which the boleto can be paid. It is different from the due date; see below. |
| `invoice_type` | Yes | Type of document that originated the charge. Values are in [Boleto types](https://docs.trio.com.br/v2/guides/boleto/boleto-types.md). |
| `wallet_type` | Yes | How the bank registers and manages the boleto. Values are in [Boleto types](https://docs.trio.com.br/v2/guides/boleto/boleto-types.md). |
| `notes` | No | Up to 3 entries with extra information that does not belong in `description`. Send `null` when there are none. |

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

```json theme={null}
"due_detail": {
  "due_date": "2026-08-17"
},
"expiration_date": "2026-10-30"
```

This boleto is due on August 17 and can be paid until October 30. The [Boleto best practices](https://docs.trio.com.br/v2/guides/boleto/best-practices.md) guide covers how each date affects updates and what happens after expiration.

### Notes

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

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

```json theme={null}
"splits": [
  {
    "counterparty_recipient_id": "0198aaaa-1111-2222-3333-444444444444",
    "type": "percentage",
    "value": 70
  },
  {
    "counterparty_recipient_id": "0198bbbb-5555-6666-7777-888888888888",
    "type": "percentage",
    "value": 30
  }
]
```

The [Split payments](https://docs.trio.com.br/v2/guides/receivables/split-payments.md) 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.

```json theme={null}
"options": {
  "fee": 0
}
```

The [Fees](https://docs.trio.com.br/v2/guides/receivables/fees.md) guide explains how the fee is settled.

### Merchant

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

```json theme={null}
"merchant": {
  "name": "Merchant Name",
  "tax_number": "12345678000199"
}
```

## Response

A successful request returns `201 Created` with the boleto under `data`:

```json theme={null}
{
  "data": {
    "id": "0196f83d-cafa-f412-1f1d-129cdf2dda49",
    "status": "confirmed",
    "amount": {
      "amount": 10000,
      "currency": "BRL"
    },
    "description": "Mensalidade agosto",
    "external_id": "boleto-demo-2026-001",
    "bank_account_id": "019f0000-1234-5678-9abc-000000000001",
    "counterparty": {
      "id": "000a89cb-f0c9-07ce-79c2-fc049bc253e0"
    },
    "barcode": "12341111222233334444555566667777888899990000",
    "digitable_line": "12341111222233334444555566667777888899990000",
    "boleto_url": "https://example.com/boleto_1",
    "due_detail": {
      "due_date": "2026-08-17",
      "discount": {
        "fixed_until_due": {
          "amounts": [
            {
              "value": 500,
              "date": "2026-08-16"
            }
          ],
          "calculation_type": "percentage"
        }
      },
      "fine": {
        "calculation_type": "percentage",
        "value": 150
      },
      "interest": {
        "calculation_type": "monthly_fee",
        "value": 300
      }
    },
    "expiration_date": "2026-10-30",
    "issue_date": "2026-08-01",
    "invoice_type": "invoice",
    "wallet_type": "book_entry_electronic_bloquete",
    "notes": [],
    "fee": {
      "amount": 0,
      "currency": "BRL"
    },
    "inserted_at": "2026-08-01T10:00:00.000000Z",
    "updated_at": "2026-08-01T10:00:00.000000Z"
  }
}
```

The fields worth keeping in your system:

| Field | Description |
| - | - |
| `id` | Trio ID of the boleto. It is also the ID of its embedded Pix QR code. |
| `status` | `created`, `confirmed`, `settled`, `onhold`, `refunded`, `failed` or `cancelled`. |
| `amount` | Boleto amount as a money object: `amount` in cents and `currency`. |
| `counterparty` | Payer the boleto is issued to, with the `id` Trio assigned. |
| `barcode` | Barcode of the boleto. |
| `digitable_line` | Digitable line of the boleto. |
| `boleto_url` | URL of the boleto, ready to share with the payer. |
| `due_detail` | The payment rules as sent. Amount-type rules come back as money objects; percentage rules keep `value` in basis points. |
| `issue_date` | Day the boleto was issued. |
| `fee` | Fee charged on the payment, as a money object. |
| `inserted_at` | When the boleto was created. |
| `updated_at` | When the boleto was last updated. |

A rule configured with `calculation_type: amount` is returned with its `amount` as a money object:

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

## 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}`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-dynamic/get). Payments reach you as webhook events; the [events overview](https://docs.trio.com.br/v2/webhooks/events/overview.md) lists them, and the [Boleto best practices](https://docs.trio.com.br/v2/guides/boleto/best-practices.md) guide covers the hybrid boleto, its lifecycle and reconciliation.

The boleto itself is managed through these endpoints:

| Operation | Endpoint | What it does |
| - | - | - |
| [Get boleto](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/get.md) | `GET /v2/in/boletos/{id}` | Returns the boleto with the same fields as the create response. |
| [Update boleto due date](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/update.md) | `PUT /v2/in/boletos/{id}` | Changes the due date. Body: `due_detail.due_date`. Returns `204 No Content`; read the boleto back to see the new due date. |
| [Recreate boleto](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/recreate.md) | `POST /v2/in/boletos/{id}/recreate` | Cancels the boleto and creates a new one with the same fields, the new `amount` and the new due date (or the current one when `due_detail` is omitted). Returns `201` with the new boleto. |
| [Cancel boleto](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/cancel.md) | `POST /v2/in/boletos/{id}/cancel` | Cancels the boleto. Returns `204 No Content`. |
| [Add protest](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/add-protest.md) | `PUT /v2/in/boletos/{id}/protest/add` | Adds protest to the boleto. Returns `204 No Content`. |
| [Remove protest](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/remove-protest.md) | `PUT /v2/in/boletos/{id}/protest/remove` | Removes protest from the boleto. Returns `204 No Content`. |

To change the due date:

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

To change the amount, recreate the boleto:

```json theme={null}
{
  "amount": 15000,
  "due_detail": {
    "due_date": "2026-09-17"
  }
}
```

A boleto paid through its Pix QR code can be refunded with [Refund a receivable](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/refunds/post.md) (`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

* [Boleto types](https://docs.trio.com.br/v2/guides/boleto/boleto-types.md): choose `invoice_type` and `wallet_type`.
* [Boleto best practices](https://docs.trio.com.br/v2/guides/boleto/best-practices.md): hybrid boleto, lifecycle, webhooks and reconciliation.
* [Split payments](https://docs.trio.com.br/v2/guides/receivables/split-payments.md): distribute the payment among recipients.
* [Fees](https://docs.trio.com.br/v2/guides/receivables/fees.md): charge a fee on the payment.


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