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

# Boleto

> Como funciona a geração de boletos bancários

# Boleto

> Gere boletos bancários registrados, pagáveis em qualquer banco, app ou lotérica

O boleto é uma boa alternativa para clientes que não usam PIX, para pagamentos agendados ou cobranças com vencimento futuro.

## Como funciona

<Steps>
  <Step title="Você gera o boleto">
    Chama o endpoint de transações com `paymentMethod: "boleto"` e o valor da cobrança.
  </Step>

  <Step title="Recebe os dados de pagamento">
    A resposta traz o link do PDF, o código de barras e a linha digitável.
  </Step>

  <Step title="Cliente paga">
    O cliente paga escaneando o código de barras ou digitando a linha digitável em qualquer banco, app bancário ou lotérica.
  </Step>

  <Step title="Confirmação após compensação">
    Diferente do PIX, a compensação bancária do boleto leva algum tempo. Assim que ela ocorre, você recebe a confirmação via [webhook](/guides/webhooks).
  </Step>
</Steps>

## Exemplo rápido

```bash theme={null}
curl -X POST 'https://api.velfy.com/api/v1/transactions' \
  -u "sk_xxx:pk_xxx" \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentMethod": "boleto",
    "amount": 25000,
    "boleto": { "expiresInDays": 3 },
    "customer": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "document": { "type": "cpf", "number": "98765432100" }
    },
    "items": [
      { "title": "Serviço Y", "unitPrice": 25000, "quantity": 1, "tangible": false }
    ]
  }'
```

A resposta traz `boleto.url` (PDF), `boleto.barcode` e `boleto.digitableLine` — disponibilize um desses para o cliente pagar.

## Ciclo de vida da cobrança

| Status     | O que significa                                              |
| ---------- | ------------------------------------------------------------ |
| `pending`  | Aguardando pagamento — disponibilize o boleto para o cliente |
| `paid`     | Pagamento compensado — libere o produto/serviço              |
| `refunded` | Valor devolvido ao cliente                                   |

## Boas práticas

* Escolha um `boleto.expiresInDays` (1 a 90) compatível com o prazo do seu produto/serviço
* Lembre o cliente que a compensação do boleto pode levar até alguns dias úteis
* Use `externalRef` para relacionar a cobrança com o pedido no seu sistema

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência técnica" icon="book" href="/api-reference/payments/boleto">
    Veja todos os campos e exemplos completos de resposta
  </Card>

  <Card title="PIX" icon="qrcode" href="/guides/pix">
    Aceite também pagamentos via PIX
  </Card>
</CardGroup>