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

# Boleto

> Crie cobrança de boleto em POST /v1/payments: customer com endereço, vencimento opcional e resposta com linha digitável e QR Pix.

Este guia descreve o contrato público de boleto em `POST /v1/payments`. Use-o para montar o request e ler a resposta.

O `paymentMethod` é `boleto`. O objeto `boleto` no body só envia o vencimento. Nome, documento e endereço ficam em `customer`.

Referência do endpoint: [Criar pagamento](/api-reference/payments/create). O PDF fica em [Consultar PDF do boleto](/api-reference/payments/get-boleto).

## Campos obrigatórios

Envie `paymentMethod: "boleto"`. O `customer` é obrigatório.

| Campo                           | Obrigatório           |
| ------------------------------- | --------------------- |
| `customer.name`                 | sim                   |
| `customer.email`                | sim                   |
| `customer.document.number`      | sim                   |
| `customer.document.type`        | sim (`cpf` ou `cnpj`) |
| `customer.address.street`       | sim                   |
| `customer.address.streetNumber` | sim                   |
| `customer.address.zipCode`      | sim                   |
| `customer.address.neighborhood` | sim                   |
| `customer.address.city`         | sim                   |
| `customer.address.state`        | sim                   |
| `customer.address.country`      | sim                   |
| `customer.address.complement`   | não                   |
| `customer.phone`                | não                   |
| `boleto.expirationDate`         | não                   |

**NOTA:** Sem `customer.address` completo a API retorna `400`. A falha ocorre na validação do body.

## Vencimento

Sem `boleto` ou sem `expirationDate`, o vencimento é 30 dias.

Se enviar `boleto.expirationDate`:

* Use ISO 8601 com offset (`Z`, `±HH:MM` ou `±HHMM`).
* A data deve estar no futuro.
* A data deve estar no máximo 30 dias à frente.

Data passada, formato inválido ou além de 30 dias: a API retorna `400`.

## Resposta

A criação retorna `status: "waiting_payment"` e `paymentMethod: "boleto"`.

| Campo                  | Conteúdo                                   |
| ---------------------- | ------------------------------------------ |
| `boleto.digitableLine` | Linha digitável                            |
| `pix.qrcode`           | Payload Pix copia-e-cola da mesma cobrança |

O PDF do boleto **não** vem na criação. Ele é gerado em background. Consulte `GET /v1/payments/{id}/boleto` até `status` ser `ready`.

`POST /v1/payments`, `GET /v1/payments/{id}` e o webhook da transação retornam só `boleto.digitableLine`.
Esses endpoints não retornam `url` nem `barcode`.

O pagador pode quitar pela linha digitável ou pelo QR Pix. O `paymentMethod` permanece `boleto`.

## PDF do boleto

`GET /v1/payments/{id}/boleto` usa a mesma autenticação de `GET /v1/payments/{id}`.

A resposta é `200` quando o pagamento existe, é do merchant e é boleto:

| `status`  | Conteúdo                                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `pending` | PDF ainda não está pronto. O header `Retry-After` traz o intervalo em segundos. Consulte de novo depois desse intervalo. |
| `ready`   | Campo `url` com URL assinada do PDF. A URL expira em 3600 s.                                                             |
| `failed`  | A geração falhou. A linha digitável continua válida.                                                                     |

O endpoint aceita 30 requests por minuto por IP. Se o limite estourar, a API retorna `429` com header `Retry-After`.

Se o pagamento não existir ou não for do merchant, a API retorna `404`. Se o pagamento não for boleto, a API retorna `422`.

**NOTA:** A `url` é assinada. Consulte o endpoint de novo quando ela expirar.

Exemplo quando o PDF está pronto:

```json theme={null}
{
  "status": "ready",
  "url": "https://storage.example/boletos/d398b016-3c29-41b4-afc0-bbf8c81c683c.pdf?X-Amz-Expires=3600"
}
```

## Estorno

**ATENÇÃO:** Boleto não aceita estorno. `PUT /v1/payments/{id}/refund` não estorna cobrança de boleto.

## Exemplo de request

```json theme={null}
{
  "externalId": "ORDER-BOLETO-1",
  "amount": 7500,
  "paymentMethod": "boleto",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@example.com",
    "document": {
      "number": "12345678901",
      "type": "cpf"
    },
    "address": {
      "street": "Avenida Paulista",
      "streetNumber": "1000",
      "zipCode": "01310100",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "country": "BR"
    }
  },
  "items": [
    {
      "title": "Produto",
      "quantity": 1,
      "unitPrice": 7500
    }
  ],
  "boleto": {
    "expirationDate": "2026-09-09T18:00:00.000Z"
  }
}
```

## Exemplo de resposta

```json theme={null}
{
  "id": "d398b016-3c29-41b4-afc0-bbf8c81c683c",
  "status": "waiting_payment",
  "amount": 7500,
  "paymentMethod": "boleto",
  "boleto": {
    "digitableLine": "34191.79001 01043.510047 91020.150008 1 98760000012345"
  },
  "pix": {
    "qrcode": "000201..."
  },
  "createdAt": "2026-08-11T15:00:00.000Z"
}
```