> ## 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 gerar um boleto bancário

# Boleto

> Gere boletos bancários para seus clientes pagarem em qualquer banco ou lotérica

## 🚀 Como Funciona

<CardGroup cols={2}>
  <Card title="🧾 Boleto gerado" color="#631286" icon="barcode">
    Você cria a cobrança e recebe a linha digitável, código de barras e PDF
  </Card>

  <Card title="🏦 Cliente paga" color="#631286" icon="building-columns">
    O cliente paga em qualquer banco, lotérica ou app bancário
  </Card>

  <Card title="⚡ Confirmação" color="#631286" icon="bolt">
    Você recebe a confirmação via webhook após a compensação bancária
  </Card>

  <Card title="💰 Saldo disponível" color="#631286" icon="money-bill">
    O valor fica disponível na sua conta Velfy
  </Card>
</CardGroup>

## 🛠️ Implementação Rápida

### 1. Criar o boleto

```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,
    "externalRef": "pedido-456",
    "boleto": { "expiresInDays": 3 },
    "customer": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "phone": "11988888888",
      "document": { "type": "cpf", "number": "98765432100" }
    },
    "items": [
      { "title": "Serviço Y", "unitPrice": 25000, "quantity": 1, "tangible": false }
    ]
  }'
```

### 2. Resposta com o boleto

```json theme={null}
{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": {
    "id": 987655,
    "status": "pending",
    "amount": 25000,
    "paymentMethod": "boleto",
    "secureId": "c1b2...uuid",
    "secureUrl": "https://pay.velfy.com/checkout/c1b2...uuid",
    "boleto": {
      "url": "https://boleto.example.com/54221d59.pdf",
      "barcode": "34191826100004000001091007175647307144464000",
      "digitableLine": "34191.09107 07175.647309 71444.640008 1 82610000400000"
    },
    "createdAt": "2026-07-28T12:00:00.000Z"
  }
}
```

### 3. Disponibilizar o boleto para o cliente

```html theme={null}
{/* Link para o PDF */}
<a href="https://boleto.example.com/54221d59.pdf" target="_blank">Baixar boleto</a>

{/* Ou exiba a linha digitável */}
<div class="boleto-code">
  <p>Linha digitável:</p>
  <input type="text" value="34191.09107 07175.647309 71444.640008 1 82610000400000" readonly />
</div>
```

## 📊 Parâmetros Detalhados

### Campo específico do boleto

| Campo                  | Tipo     | Descrição                                                        |
| ---------------------- | -------- | ---------------------------------------------------------------- |
| `boleto.expiresInDays` | `number` | Prazo de vencimento do boleto, em dias — de 1 a 90 (padrão: `2`) |

<Info>
  Consulte os [campos comuns a toda transação](/api-reference/payments/transactions) para os demais parâmetros (`amount`, `customer`, `items`, etc).
</Info>

## 📋 Status da Transação

| Status     | Descrição            | Próximo Passo                         |
| ---------- | -------------------- | ------------------------------------- |
| `pending`  | Aguardando pagamento | Disponibilize o boleto para o cliente |
| `paid`     | Pagamento compensado | Libere o produto/serviço              |
| `refunded` | Estornado            | Valor devolvido ao cliente            |

## 🛡️ Boas Práticas

<AccordionGroup>
  <Accordion title="🔒 Validação de dados" icon="shield-check">
    * Valide CPF/CNPJ antes de enviar a requisição
    * Confirme que o valor de `amount` corresponde à soma dos itens
  </Accordion>

  <Accordion title="🔄 Idempotência" icon="arrows-rotate">
    * Use `externalRef` para relacionar a cobrança com seu pedido interno
    * Trate reenvios de webhook de forma idempotente
  </Accordion>
</AccordionGroup>

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="🔗 Configurar Webhooks" color="#631286" icon="webhook" href="/api-reference/payments/webhooks">
    Receba a confirmação do pagamento automaticamente
  </Card>

  <Card title="💰 PIX" color="#631286" icon="qrcode" href="/api-reference/payments/pix">
    Aceite também pagamentos via PIX
  </Card>
</CardGroup>