> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Boletos
> Issue boletos from the Payments plugin for Midaz, track their lifecycle states, and handle issuance and payment errors.
The **Boletos** page lets you issue boletos and follow them through their lifecycle. In this section, you'll learn how to issue a boleto via the [Lerian Console](/en/lerian-console/about-lerian-console), which fields are required, the states a boleto can move through, and how to handle errors.
## Accessing the Boletos page
***
To open the **Boletos** page, click **Payments** → **Boletos** from the left-side menu.
The page displays all boletos for the organization in a data table, with the following columns:
* **Boleto** — the boleto identifier (and barcode/digitable line when issued).
* **Payer** — the party being charged.
* **Amount** — the boleto amount.
* **Due Date** — the date the boleto is due.
* **Status** — the current lifecycle state (see [States](#boleto-states)).
* **Created At** — the date the boleto was issued.
* **Actions** — action menu.
You can filter boletos by status, payer, or date range using the filter fields above the table.
## Issuing a boleto
***
To issue a boleto, click the **+ Issue new boleto** button on the top-right of the **Boletos** page. A side panel opens with three tabs — choose the issuance type that fits your use case:
### Boleto types
| Type | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| **Single** | Issue one boleto for a single payer with a fixed amount and due date. |
| **Installments** | Issue a series of boletos for the same payer, split over multiple due dates at a configured interval. |
| **Batch** | Issue up to 10 boletos for different payers in one operation. Each entry is sent individually to the provider. |
### Registration type
All three issuance types include a **Type** field:
* **Traditional** — standard boleto registered with the banking provider.
* **Hybrid** — boleto with a Pix QR code embedded, allowing the payer to pay via barcode or QR code.
### Single boleto
From the **Boletos** page, click **+ Issue new boleto**.
Select the **Single** tab.
Fill in the required fields:
**Boleto details**
* **Amount** *(required)* — the boleto value (R\$).
* **Due date** *(required)* — the date by which the boleto must be paid.
* **Account ID** *(required)* — the Midaz account to associate with the boleto.
* **Type** *(required)* — **Traditional** or **Hybrid**.
**Payer details**
* **CPF / CNPJ** *(required)* — the payer's tax document.
* **Full name** *(required)* — the full name of the payer.
* **Street** *(required)* — payer's street address.
* **Number** *(required)* — address number.
* **Complement** *(optional)* — apartment, suite, or additional address info.
* **Neighborhood** *(required)* — payer's neighborhood.
* **City** *(required)* — payer's city.
**Additional**
* **Instructions** *(optional)* — instructions printed on the boleto (e.g., interest or fines after the due date).
Click **Issue boleto**.
Once processed, the boleto appears in the list with its generated **barcode** and **digitable line**, ready to be shared with the payer.
### Installment series
Same fields as Single, with the following differences:
* **Total amount** *(required)* — the full amount to be split across all installments.
* **First due date** *(required)* — the due date for the first installment; subsequent boletos are generated automatically.
* **Installments** *(required)* — number of boletos to generate (minimum 2).
* **Interval (days)** *(required)* — number of days between each due date (default 30).
Click **Issue installment series** to confirm.
### Batch
The **Batch** tab lets you issue up to 10 boletos at once. Each entry is sent individually to the provider.
For each entry, fill in: **Amount**, **Due date**, **Account ID**, **CPF / CNPJ**, and **Full name**. Use **+ Add entry** to add more entries. The counter shows how many entries are queued (e.g., `1 / 10 entries`).
Click **Issue batch** to submit all entries.
After a boleto is issued, copy the **digitable line** or download the boleto document to share it with the payer.
## Boleto states
***
A boleto moves through the following states:
* **Registering** — the boleto issuance request was submitted and is being registered.
* **Registered** — the boleto was successfully registered and can be paid by the payer.
* **Paid** — the payer has paid the boleto.
* **Expired** — the boleto passed its due date without payment.
* **Cancelled** — the boleto was cancelled before payment.
* **Failed** — the issuance request could not be completed (see [Error handling](#error-handling)).
## Available actions menu
***
For each boleto, the following actions may be available in the action menu (), depending on its state:
* **View details** — opens the boleto details, including barcode, digitable line, and status history.
* **Download** — downloads the boleto document.
* **Cancel** — cancels a boleto that has not yet been paid.
## Error handling
***
If a boleto cannot be issued, it appears with a **Failed** status and an error reason in the details panel. Common causes include:
* **Invalid payer document** — the CPF/CNPJ is malformed or fails validation. Correct the document and issue a new boleto.
* **Invalid amount or due date** — the amount is zero/negative or the due date is in the past. Adjust the values and retry.
* **Provider/registration error** — the registration could not be completed with the banking provider. Retry the issuance; if it persists, contact support.
Issuing boletos requires the appropriate Payments permissions. If you can't see the **+ Issue new boleto** button, check your role permissions with your administrator.
## Related pages
***