> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Boleto bancário

> Fluxo completo de cobrança via boleto bancário em mode=payment.

Boleto é um método **assíncrono** — o comprador recebe um documento bancário,
paga em banco/app/internet banking, e o resultado da compensação chega
**1 dia útil depois** (no mínimo). A integração reflete isso: o
`payment_intent` fica em `pending` com o documento renderizado em
`next_action`, e o `payment.intent.succeeded` chega via webhook quando o
banco confirma.

## Pré-requisitos

Boleto exige **endereço completo do comprador** por regulamentação FEBRABAN.
Ao confirmar uma checkout session com `payment_method: "boleto"`, os seguintes
campos são obrigatórios:

| Campo                                   | Validação                     |
| --------------------------------------- | ----------------------------- |
| `customer_name`                         | Não vazio.                    |
| `customer_email`                        | Email válido.                 |
| `customer_document`                     | CPF ou CNPJ do pagador.       |
| `customer_billing_address.country`      | Apenas `"BR"`.                |
| `customer_billing_address.state`        | UF de 2 letras (ex.: `"SP"`). |
| `customer_billing_address.postal_code`  | CEP (8 dígitos).              |
| `customer_billing_address.city`         | Não vazio.                    |
| `customer_billing_address.street`       | Logradouro.                   |
| `customer_billing_address.neighborhood` | Bairro.                       |

Falhar qualquer um retorna um erro `422` por parâmetros inválidos.

<Info>
  `POST /v1/payment-intents` aceita cartão e Pix no fluxo direto. Um payment
  intent de boleto nasce por checkout hospedado ou invoice; não envie
  `payment_method_types: ["boleto"]` no create direto.
</Info>

## Lifecycle

| Momento                                     | Estado do Payment Intent  | Campos e eventos                                                                                                                 |
| ------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Confirmação                                 | `pending`                 | `next_action.boleto_display_details` é preenchido; são emitidos `payment.intent.created` e `payment.intent.updated`.             |
| Comprador paga e a compensação é confirmada | `succeeded`               | São emitidos `charge.succeeded`, `payment.intent.succeeded` e, quando aplicável, `checkout.session.async.payment.succeeded`.     |
| Comprador não paga até `expires_at`         | `requires_payment_method` | O job de expiração encerra a tentativa; são emitidos `charge.failed` e `payment.intent.updated`. O intent aceita um boleto novo. |

## Lendo `next_action.boleto_display_details`

```json theme={"theme":"css-variables"}
{
  "boleto_display_details": {
    "barcode": "23791966600000149903381286008296100211202300",
    "expires_at": "2026-05-19",
    "hosted_voucher_url": "https://example.com/boletos/abc.pdf",
    "number": "23793.38128 60082.961002 11202.300008 1 96660000014990",
    "pdf": "https://example.com/boletos/abc.pdf"
  },
  "type": "boleto_display_details"
}
```

| Campo                | Uso                                                                   |
| -------------------- | --------------------------------------------------------------------- |
| `number`             | Linha digitável (47 dígitos). Para copiar e colar em app bancário.    |
| `barcode`            | Código de barras (44 dígitos, extensão BR). Para leitura por scanner. |
| `pdf`                | URL do PDF do boleto para download/impressão.                         |
| `hosted_voucher_url` | URL hospedada para visualizar o documento. Pode coincidir com `pdf`.  |
| `expires_at`         | Data de vencimento (formato `YYYY-MM-DD`).                            |

<Note>
  Trate `hosted_voucher_url` e `pdf` como campos independentes, mesmo quando as
  duas URLs apontarem para o mesmo documento.
</Note>

## Auto-expiração

A Chargefy agenda automaticamente um job para encerrar a tentativa no momento
de `expires_at` se o pagamento não tiver sido confirmado. O vencimento encerra
o boleto, não o Payment Intent. Quando isso ocorre:

* O intent volta a `requires_payment_method` e `payment.intent.updated` é
  emitido; a expiração não cancela o intent.
* `charge.failed` é emitido com `payment_error.message: "Boleto expired without payment"`.
* O documento atual é invalidado quando possível e `next_action` volta a
  `null`.

Não é preciso fazer polling para detectar expiração — escute o webhook.

## Reemitir um boleto vencido (regenerate)

Depois que um boleto vence, use
[`POST /v1/payment-intents/{id}/regenerate_boleto`](/api-reference/payment-intents/regenerate-boleto)
para emitir outro dentro do mesmo Payment Intent. Um boleto `pending` ou
`processing` ainda pode ser pago e não é reemitido. Mantém:

* Mesmo ID de `payment_intent` e mesmo `client_secret`.
* Mesmo vínculo com a checkout session (se aplicável).
* Novo `latest_charge`, novo `next_action`, novo `expires_at`.

Limitado a 1 chamada por hora por Payment Intent (`429` caso contrário).
Sem limite total de reemissões.