> 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 Pay

Pays a boleto someone else issued. The account is the payer. Issuing a boleto for your own account is [Boleto Issuance Guide](/baas/guias/cobranca/boleto-charge).

Boleto is the other cash out available on v2 (on v1 these endpoints answered
`503`). There are three routes: one to read the boleto before paying, one to
pay, and one to check the outcome.

### Step 1: Preview (read the boleto)

Resolves the payment line at the partner and returns `200` with the details of
the bill (beneficiary, payer, amount, due date) so you can show it before
debiting.

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/boleto/preview" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{ "line": "34191790010104351004791020150008291070026000" }'
```

The canonical field is `line`; `barcode` is accepted as an alias. A boleto the
partner cannot find returns `404 not_found`.

```json
{
  "type": "boleto-payment",
  "bank": "Itaú Unibanco S.A.",
  "bankCode": "341",
  "receiverName": "FORNECEDOR EXEMPLO LTDA",
  "receiverTaxId": "12345678000190",
  "dueDate": "2026-08-10",
  "amount": 1430.63,
  "discountAmount": 0,
  "interestAmount": 3.29,
  "fineAmount": 28.61,
  "totalUpdated": 1462.53,
  "status": "PAYABLE"
}
```

> **Pay \`totalUpdated\`, not \`amount\`**
>
> `amount` is the face value — the very number encoded in the barcode.
> `totalUpdated` is what the settlement bank accepts **today**: face + interest +
> fine − discount.
>
> On an overdue slip the two differ, and the settlement bank rejects any value
> other than the updated one (`boleto_amount_mismatch`). Since charges accrue by
> the day, yesterday's `totalUpdated` is already stale: run the preview on the day
> you pay, and fund the account for the updated amount, not the face value.

### Step 2: Pay

```bash
curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/boleto/pay" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "line": "34191790010104351004791020150008291070026000",
       "amount": 1462.53,
       "taxId": "12345678000199",
       "description": "ACME supplier"
     }'
```

| Parameter             | Required | Description                                                      |
| --------------------- | -------- | ---------------------------------------------------------------- |
| `line` (or `barcode`) | Yes      | Payment line / barcode                                           |
| `amount`              | Yes      | Amount to pay — the preview's `totalUpdated`, not the face value |
| `taxId`               | No       | Payer's CNPJ/CPF                                                 |
| `scheduled`           | No       | Scheduling, where the partner supports it                        |
| `description`         | No       | Free-text description                                            |

A divergent amount comes back as `boleto_amount_mismatch` (422), and the message
carries the amount the settlement bank expects — re-run the preview and resend
with it.

**The response is always `202`**, never `200`: the payment runs asynchronously
and the body carries `paymentId` (= `boletoId`, shaped `bol_{uuid}`),
`status: "PROCESSING"` and a `Location` header pointing at the status lookup.

```json
{
  "paymentId": "bol_aabbccdd-...",
  "boletoId": "bol_aabbccdd-...",
  "idempotencyKey": "...",
  "amount": 250.00,
  "status": "PROCESSING"
}
```

The `boletoId` is derived from (`accountId`, `Idempotency-Key`), so repeating the
request with the **same** key returns the same `paymentId` and reuses the run in
flight — no double debit.

### Step 3: Check the outcome

```bash
curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/boleto/payments/bol_aabbccdd-..." \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"
```

Accepts both the canonical `paymentId` (`bol_...`) and the partner reference.
While the partner has not returned a reference yet, the route answers `200` with
the last known local status (`PROCESSING`) instead of an error.

The outcome also arrives by webhook: `boleto.paid` and `boleto.failed` (see
[Webhooks](/baas/guias/conta/webhooks)). Settling a boleto can take hours — up to the next
business day — so treat `PROCESSING` as a normal, long-lived state rather than a
failure.