Boleto

Gere boletos registrados: linha digitável, código de barras e PDF na resposta. Liquidação D+1.

Referência rápida

Criar boleto

Cria uma cobrança via boleto bancário registrado. Use o mesmo endpoint de cobranças com paymentMethod: "BOLETO". A resposta traz a linha digitável, o código de barras e o link do PDF. O boleto é sempre emitido por um provedor de boleto fixo, independente do provider Pix da conta.

POST/v1/charges

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

Body (JSON)

paymentMethodstringobrigatório

Use "BOLETO" para emitir um boleto (padrão: "PIX").

amountnumberobrigatório

Valor em centavos (mín. 100 = R$ 1,00)

externalIdstringobrigatório

ID do pedido no seu sistema. Garante idempotência e conciliação 1:1.

payerNamestringobrigatório

Nome do pagador.

payerDocumentstringobrigatório

CPF/CNPJ do pagador. Obrigatório no boleto.

dueDatestringopcional

Vencimento (ISO 8601). Opcional, padrão: 3 dias a partir da emissão.

payerAddressobjectopcional

Endereço do pagador (objeto com zipCode, line1, city, state). Opcional: na ausência, usamos o endereço de fallback configurado.

descriptionstringopcional

Descrição da cobrança.

payerEmailstringopcional

Email do pagador.

Parâmetro	Tipo	Obrigatório	Descrição
`paymentMethod`	string	Sim	Use "BOLETO" para emitir um boleto (padrão: "PIX").
`amount`	number	Sim	Valor em centavos (mín. 100 = R$ 1,00)
`externalId`	string	Sim	ID do pedido no seu sistema. Garante idempotência e conciliação 1:1.
`payerName`	string	Sim	Nome do pagador.
`payerDocument`	string	Sim	CPF/CNPJ do pagador. Obrigatório no boleto.
`dueDate`	string	Não	Vencimento (ISO 8601). Opcional, padrão: 3 dias a partir da emissão.
`payerAddress`	object	Não	Endereço do pagador (objeto com zipCode, line1, city, state). Opcional: na ausência, usamos o endereço de fallback configurado.
`description`	string	Não	Descrição da cobrança.
`payerEmail`	string	Não	Email do pagador.

/v1/charges

curl -X POST https://api.pagniv.com/v1/charges \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "BOLETO",
    "amount": 15000,
    "externalId": "pedido-1234",
    "payerName": "Maria Silva",
    "payerDocument": "12345678900",
    "dueDate": "2026-01-23",
    "payerAddress": {
      "zipCode": "01310930",
      "line1": "Avenida Paulista, 1106",
      "city": "São Paulo",
      "state": "SP"
    }
  }'

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "txid": "ch_abc123def456",
    "paymentMethod": "BOLETO",
    "amount": 15000,
    "feeAmount": 99,
    "netAmount": 14901,
    "status": "PENDING",
    "digitableLine": "23793.38128 60082.123456 78901.234567 8 99230000015000",
    "barcode": "23793993300000150003812860082123456789012345678",
    "boletoUrl": "https://boleto.pagniv.com/ch_abc123def456.pdf",
    "dueDate": "2026-01-23T00:00:00Z",
    "expiresAt": "2026-01-26T00:00:00Z",
    "createdAt": "2026-01-15T11:00:00Z"
  }
}

Pagamento após o vencimento

O boleto pode ser pago no dia do vencimento ou em até 3 dias depois (prazo de graça). A confirmação chega pelo mesmo webhook de cobranças (evento charge.paid) assim que o pagamento é compensado.

Boleto precisa estar habilitado

Assim como o cartão, o boleto depende de habilitação pela Pagniv para a sua conta. Enquanto não liberado, a criação retorna 403 BOLETO_NOT_ENABLED. Fale com o suporte para habilitar.