> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Boleto Issuance Guide

Issue a boleto on behalf of the account. The account is the beneficiary and a third party pays. The other direction, paying someone else's boleto, is [Boleto Pay](/baas/guias/pagar/boleto-pay).

The `boleto_charge` feature **starts disabled for every tenant**, including tenants created after this release. While it is off, every route under `/v1/accounts/{accountId}/boleto/charge` returns **403** `feature_disabled`. With the feature on, issuance still requires `boletoCharge.enabled = true` on the tenant policy (every account) or on the account policy. Otherwise the route returns **403** `boleto_charge_account_disabled`. `enabled = false` on the account policy opts that account out of a tenant-wide enable. CorpX turns both on from the admin panel. Turning the feature off later does not cancel a boleto already issued.

Credential scope: `boleto_charge.manage`. This is money in, not cashout. Reads also accept `read`. Single issuance and batches are **BaaS** operations; Internet Banking credentials remain read-only for boleto charges.

## Register the beneficiary

The holder must be a beneficiary at the settlement bank before the first issuance. Registration uses the account's own data (name, tax id and, when the holder has more than one active account, branch and account). **Do not send a body.** Any JSON other than empty or `{}` returns **400** `invalid_payload`.

```
POST /v1/accounts/{accountId}/boleto/charge/beneficiary
```

| Situation                                  | HTTP                                                | What happens                                                                                                                                                    |
| ------------------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No beneficiary, or a closed relationship   | 202 `boleto_charge_beneficiary_pending`             | The facade registers and stops. Header `Retry-After: 300`. Nothing was issued.                                                                                  |
| Already `PENDING`                          | 202, same code                                      | No second registration.                                                                                                                                         |
| `ELIGIBLE` with relationship `ACTIVE`      | 200                                                 | Returns the beneficiary. Does not register again.                                                                                                               |
| `INELIGIBLE` or `UNDER_REVIEW`             | 422 `boleto_charge_beneficiary_ineligible`          | The message carries the status.                                                                                                                                 |
| The settlement bank rejects synchronously  | 502 `boleto_charge_beneficiary_registration_failed` | The message carries the bank's description. Nothing was issued.                                                                                                 |
| Registration rejected in the last 24 hours | As in the rows above                                | This `POST` registers again anyway: it is how you re-register after fixing the account data. Only automatic re-registration by issuance waits for the 24 hours. |

```
GET /v1/accounts/{accountId}/boleto/charge/beneficiary
```

Live read. **404** `boleto_charge_beneficiary_not_found` when the account was never registered. **422** `boleto_charge_account_holder_not_found` when the settlement bank does not recognize the holder in the boleto module: that is not a missing beneficiary.

| Field                | Values                                                                                                                                                            |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`             | `ELIGIBLE`, `PENDING`, `UNDER_REVIEW`, `INELIGIBLE`                                                                                                               |
| `relationshipStatus` | `ACTIVE` or `CLOSED`                                                                                                                                              |
| `relationshipActive` | `true` when the relationship is active                                                                                                                            |
| `lastEvent`          | Latest notice from the settlement bank about the beneficiary, when there is one. See [Tracking the beneficiary by webhook](#tracking-the-beneficiary-by-webhook). |

```
PATCH /v1/accounts/{accountId}/boleto/charge/beneficiary
```

Updates registration data. The facade resolves the beneficiary from the account; do not send the id. A person account accepts `name` and `socialName`. A company account accepts `legalName` and `tradeName`. Email, phone and representative apply to both. At least one field. **202** returns `operationId`.

```
PATCH /v1/accounts/{accountId}/boleto/charge/beneficiary/status
```

`targetStatus` is `ELIGIBLE`, `UNDER_REVIEW` or `INELIGIBLE`. Transitions: eligible goes to under review or ineligible; under review goes to eligible or ineligible; ineligible only returns to under review. Anything else is **409** `boleto_charge_beneficiary_transition_invalid` and is not sent to the bank. `reason` is required. `documentId` is required when the target is `INELIGIBLE`.

```
DELETE /v1/accounts/{accountId}/boleto/charge/beneficiary/relationship
```

Closes the relationship. After confirmation, the account cannot issue new boletos. Register again to come back. `reason` is required. `terminationDate` is optional, `YYYY-MM-DD`, today or later in Brasília time. **202** carries `operationId`.

```
GET /v1/boleto/charge/beneficiaries
```

Lists beneficiaries from the settlement bank and keeps only tax numbers of the tenant's accounts. The page is the bank's page, so it can come back shorter. `hasNext` means the bank has another page.

The first `POST /boleto/charge` also registers on its own, with the same 202, if you have not called registration first.

### Tracking the beneficiary by webhook

Registration, update, eligibility change and closure are confirmed by the settlement bank after the **202**. Subscribe to the events below to learn the outcome without repeating the call on every `Retry-After`. Each payload is described in [Webhooks](/baas/guias/conta/webhooks).

| Event                                | When                                                                                                                                                                       |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `boleto.charge.beneficiary.approved` | Registration (or reactivation) was confirmed. The account can issue.                                                                                                       |
| `boleto.charge.beneficiary.rejected` | The settlement bank rejected an operation. `operation` says which: `INCLUSION`, `UPDATE`, `STATUS_UPDATE` or `TERMINATION`. `rejectionCode` and `rejectionReason` say why. |
| `boleto.charge.beneficiary.updated`  | A registration update (`UPDATE`) or eligibility change (`STATUS_UPDATE`, with `previousStatus` and `currentStatus`) was applied.                                           |
| `boleto.charge.beneficiary.closed`   | The relationship was closed. The account cannot issue new boletos until it is registered again.                                                                            |

`data.operationId` is the same `operationId` returned by the 202 of the `PATCH` or `DELETE`. Deduplicate on the envelope `id`: the same notice can arrive more than once.

`GET .../beneficiary` returns the latest notice in `lastEvent`, with `eventType`, `operation`, `result` (`CONFIRMED` or `REJECTED`), `operationId`, `rejectionCode`, `rejectionReason` and `occurredAt`. When the account has no beneficiary yet, the **404** carries the same object in `details.lastEvent`.

A rejected registration holds automatic re-registration by issuance for 24 hours, counted from the rejection notice. During that window, `POST /boleto/charge` and batch dispatch return **502** `boleto_charge_beneficiary_registration_failed` with the reason and `details.lastEvent`, and do not send another registration. The `Retry-After` header carries the seconds left. Retrying issuance before that does not help: fix the account data and call `POST .../beneficiary`, which registers again right away and returns the usual **202**. Otherwise the **202** with `Retry-After` is unchanged: the webhook only tells you sooner.

## Monthly quotas

Two quotas are enforced together in the Brasília calendar month (`America/Sao_Paulo`):

| Quota      |             Default | Configuration                                         |
| ---------- | ------------------: | ----------------------------------------------------- |
| Tenant     | 100 issuances/month | `boletoCharge.maxIssuesPerMonth` in the tenant policy |
| PF account |   5 issuances/month | account policy                                        |
| PJ account |  10 issuances/month | account policy                                        |

There is no unlimited mode. The effective balance is always the lower of tenant and account. Read both with:

```
GET /v1/accounts/{accountId}/boleto/charge/quota
```

The response carries `periodStart`, `resetsAt`, `effectiveRemaining`, and `tenant` / `account` blocks (`limit`, `used`, `remaining`, `source`). `account.personType` is `PF` or `PJ`; `source` says whether the limit came from `default`, `tenant`, or `account`.

An issuance consumes quota only after the beneficiary has been validated and the operation admitted. An idempotent repeat of the same boleto, a pending/ineligible beneficiary, and a quota denial do not count. A definitive settlement-bank rejection (4xx, no boleto created) **returns** the slot. A timeout or an ambiguous response does not: the boleto may have been issued.

## Issue

```
POST /v1/accounts/{accountId}/boleto/charge
```

`identifier` is required in the JSON body and is this operation's only idempotency key. The `Idempotency-Key` header does **not** replace it. Repeating the same boleto returns **200** without issuing another or consuming quota again.

The **202** carries `chargeId` (the settlement bank's id), `barcode`, `digitableLine`, `ourNumber` and `registrationCondition: PENDING`. Registration at the central base arrives later as `boleto.charge.registered` or `boleto.charge.registration_failed`.

### Request fields

Money is a `number` in BRL with two decimal places. Never cents, never a string.

| Field                                                                                                                           | Required | Meaning                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `identifier`                                                                                                                    | Yes      | Idempotency for this account. Unique per account; there is no header fallback.                                                             |
| `dueDate`                                                                                                                       | Yes      | Due date, `YYYY-MM-DD`. Not before `issueDate`.                                                                                            |
| `issueDate`                                                                                                                     | No       | Issue date, `YYYY-MM-DD`.                                                                                                                  |
| `amount.nominal`                                                                                                                | Yes      | Face amount, greater than zero.                                                                                                            |
| `amount.currency`                                                                                                               | No       | `BRL`.                                                                                                                                     |
| `payer.name`                                                                                                                    | Yes      | Payer name.                                                                                                                                |
| `payer.personType`                                                                                                              | Yes      | `person` or `company`.                                                                                                                     |
| `payer.taxNumber`                                                                                                               | Yes      | CPF when `person`, CNPJ when `company`. Digits only.                                                                                       |
| `payer.email`                                                                                                                   | No       | Payer email.                                                                                                                               |
| `payer.addressStreet`, `addressNumber`, `addressComplement`, `addressDistrict`, `addressCity`, `addressState`, `addressZipCode` | No       | Payer address. ZIP is 8 digits.                                                                                                            |
| `interest`                                                                                                                      | No       | Interest after the due date. `startDate` must be after `dueDate`.                                                                          |
| `fine`                                                                                                                          | No       | Fine after the due date. Same `startDate` rule.                                                                                            |
| `discount`                                                                                                                      | No       | Early-payment discount. Each `groups[].limitDate` must be before `dueDate`.                                                                |
| `abatement.amount`                                                                                                              | No       | Fixed abatement, not negative. Together with discounts it must not reach `amount.nominal`.                                                 |
| `allowPartialPayment`                                                                                                           | No       | Accepts a payment below the amount.                                                                                                        |
| `allowDivergentPayment`                                                                                                         | No       | Accepts an amount other than face value, within `minPaymentAmount` and `maxPaymentAmount`.                                                 |
| `divergentPaymentMode`                                                                                                          | No       | `anyValue`, `minMax` or `minOnly`.                                                                                                         |
| `expirationPolicy.allowPaymentAfterDueDate`                                                                                     | No       | Whether the boleto can be paid after the due date.                                                                                         |
| `expirationPolicy.paymentLimitDate`                                                                                             | No       | Last day payment is accepted, `YYYY-MM-DD`, not before `dueDate`. This is how you bound validity: there is no write-off of an open boleto. |
| `expirationPolicy.blockPaymentAfterLimit`                                                                                       | No       | Rejects payment after `paymentLimitDate`.                                                                                                  |
| `expirationPolicy.decursoGraceDays`                                                                                             | No       | Grace days after the limit.                                                                                                                |

`interest` and `fine` share the charge shape: `calculationModel`, `typeId`, `typeKey`, `value` and `startDate`. `typeId` is optional: when omitted we fill it from `typeKey`; when sent, it must match. `discount.groups[]` carries `sequence`, `typeId`, `typeKey`, `value` and `limitDate`. A `typeKey` containing `percentage` treats `value` as a percent of face value; otherwise `value` is BRL.

| Charge              | Accepted `typeKey`                                                                                                                                                                                                                                       |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `interest`          | `exempt`, `fixed-value-calendar-day`, `fixed-value-business-day`, `percentage-calendar-day`, `percentage-business-day`, `percentage-month-calendar-day`, `percentage-month-business-day`, `percentage-year-calendar-day`, `percentage-year-business-day` |
| `fine`              | `exempt`, `fixed-value`, `percentage`                                                                                                                                                                                                                    |
| `discount.groups[]` | `exempt`, `fixed-value-until-date`, `percentage-until-date`, `fixed-value-anticipation-calendar-day`, `fixed-value-anticipation-business-day`, `percentage-anticipation-calendar-day`, `percentage-anticipation-business-day`                            |

`calculationModel`, when sent, is `receiver-calculates-all`, `recipient-calculates-overdue` or `recipient-calculates-all`. `value` is required and greater than zero except for `exempt`. `-until-date` discounts require `limitDate`; anticipation discounts must not send it. A `typeKey` or `calculationModel` outside these lists returns **400** `invalid_payload`.

A charge that disagrees with its model returns **422** `boleto_charge_rules_inconsistent`. A bad discount date returns **422** `boleto_charge_discount_invalid`. Abatement plus discounts that zero the boleto return **422** `boleto_charge_reductions_exceed_amount`. An identifier already active returns **409** `boleto_charge_identifier_in_use`. A barcode already active returns **409** `boleto_charge_barcode_active`.

### Response fields

| Field                                               | Meaning                                                                                                   |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `chargeId`                                          | Settlement-bank id. This is the path id and the id in webhooks.                                           |
| `identifier`                                        | Yours.                                                                                                    |
| `barcode`                                           | 44-digit barcode, once the bank has returned it.                                                          |
| `digitableLine`                                     | Digitable line.                                                                                           |
| `ourNumber`                                         | Our number.                                                                                               |
| `status`                                            | `OPEN`, `SETTLED`, `OVERDUE`, `WRITTEN_OFF`, `CANCELLED`, `EXPIRED`. `OVERDUE` does not close the boleto. |
| `statusReason`                                      | When the bank sends one: `termExpiration`, `settlement`, `manualWriteOff`, `cancellation`, `other`.       |
| `registrationCondition`                             | `PENDING` (central base), `REGISTERED`, `REJECTED`.                                                       |
| `dueDate`, `paymentLimitDate`                       | `YYYY-MM-DD`.                                                                                             |
| `amount.nominal`                                    | Face amount.                                                                                              |
| `amount.updatedAmount`                              | Updated amount, once the bank has applied interest, fine and discount.                                    |
| `amount.currency`                                   | `BRL`.                                                                                                    |
| `payer.name`, `payer.taxNumber`, `payer.personType` | Who must pay.                                                                                             |
| `payment.amount`, `payment.settledAt`               | Set when the boleto was settled.                                                                          |

## Consult

```
GET /v1/accounts/{accountId}/boleto/charge
GET /v1/accounts/{accountId}/boleto/charge/{chargeId}
```

The two reads have different guarantees:

* **Local list.** The first GET pages through the local mirror and does not call the settlement bank. Every item has `updatedAt`, the instant of the last successful synchronization. Filters: `barcode` (44 digits), `payer` (name or tax id), `dueDate`, `status`, `page` (minimum 1), and `pageSize` (1 to 200, default 50). The response carries `items`, `page`, `pageSize`, `totalItems`, `totalPages`, and `hasNext`.
* **Always-live detail.** The GET with `{chargeId}` calls the settlement bank every time, updates the mirror, and returns the current result with the new `updatedAt`. If the settlement bank fails, the API returns an error; it **never** serves an old cached result.

There is no historical backfill. The list starts with new v2.85.0 issuances. An older boleto enters the mirror after a successful detail lookup.

## Issue in batches

Batch routes are BaaS-only and require `boleto_charge.manage`.

1. `POST /v1/accounts/{accountId}/boleto/charge/batches` creates an empty `DRAFT`. It requires `Idempotency-Key`; the optional JSON body accepts `name` (up to 120 characters).
2. `PUT .../batches/{batchId}/items` adds 1–50 JSON requests per call.
3. `DELETE .../batches/{batchId}/items/{itemId}` removes an item while the batch is still `DRAFT`.
4. `POST .../batches/{batchId}/dispatch` reserves quota and starts asynchronous processing.
5. `GET .../batches/{batchId}?page=1&pageSize=50` follows statistics and per-item results. `GET .../batches` lists the account's batches.

Every item uses exactly the single-issuance body, including the required `identifier`. A chunk upload is **atomic**: if one item is invalid or conflicts, none of the 1–50 is stored. A batch accepts at most **5,000** items. `boleto_charge_batch_chunk_invalid` means the chunk is outside the 1–50 range; `boleto_charge_batch_too_large` means the batch would exceed 5,000; and `boleto_charge_batch_item_conflict` means the same `identifier` has another payload in the batch.

Only `DRAFT` is editable. States are:

```text
DRAFT → QUEUED → PROCESSING → COMPLETED | PARTIAL_FAILED | FAILED
```

Dispatch is atomic too: every item must fit both the tenant **and** account remaining balances at once. If either balance is too small, the API returns **429** `boleto_charge_monthly_limit_exceeded`, reserves nothing, starts no issuance, and leaves the batch in `DRAFT`. Once the batch is admitted, the reservation covers the items. An item the settlement bank rejects definitively returns its slot. An item that times out or gets an ambiguous response keeps its slot.

> **Dispatch creates billable issuances**
>
> Each boleto sent for issuance may incur charges under the commercial terms agreed with CorpX. Review the items and quota before dispatch. The Portal asks for explicit confirmation on screen; that is a UI safeguard, not an API field.

### Batch statistics

`statistics.generation` tracks `total`, `pending`, `processing`, `issued`, `failed`, and `progressPercentage`. A batch finishes when all **issuance attempts** finish; registration, payment, and expiration continue on each individual boleto.

`statistics.payment` tracks `issued`, `paid`, `unpaid`, `overdue`, `paidAmount`, and `conversionRate`. Conversion is:

```text
paid / issued × 100
```

Failed issuance items are excluded from the denominator. Payment statistics therefore keep changing after the batch reaches a terminal state.

When all attempts finish, the API sends `boleto.charge.batch.completed` with the final state and a generation summary (`total`, `issued`, `failed`). Read the batch for current payment conversion. With an HMAC subscription, validate `X-Signature` over the raw bytes and deduplicate on the envelope `id`.

## Lifecycle

1. Beneficiary registration, if there is none yet (202, a few minutes). `boleto.charge.beneficiary.approved` or `.rejected` reports the outcome.
2. Issuance (202). The boleto starts `OPEN` with registration `PENDING`.
3. `boleto.charge.registered` or `boleto.charge.registration_failed`.
4. Then `boleto.charge.settled` (also a `BOLETO` line on the statement), `overdue`, `written_off`, `cancelled` or `expired`.

`boleto.charge.failed` is in the catalog and is not sent in this version.

There is no way to write off an open boleto. The settlement bank does not offer that yet; `DELETE` exists in the code, returns 501, and is outside this contract. When validity must be predictable, send `expirationPolicy.paymentLimitDate` at issuance.