Boleto - UvviPay Public API

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. O PDF fica em Consultar PDF do 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:

{
  "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

{
  "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

{
  "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"
}

​Campos obrigatórios

​Vencimento

​Resposta

​PDF do boleto

​Estorno

​Exemplo de request

​Exemplo de resposta