Consultando um Boleto
Consultando um Boleto
A consulta de um boleto na API do Pagou permite recuperar detalhes de um boleto existente, como status, valor, código de barras e data de pagamento, usando seu ID único.
Visão Geral Técnica
O endpoint GET
/v1/charges/{id}
retorna os detalhes completos de um boleto, incluindo informações do pagador, multas, juros, descontos e status. A operação é síncrona e ideal para verificar o estado de um boleto sem depender de webhooks, embora o uso de webhooks (ex.: evento ChargePaid
) seja recomendado para atualizações automáticas.
GET
/v1/charges/{id}
Cabeçalhos
X-API-KEY
sua_chave_api
Chave de autenticação (encontrada em Configurações > API).
Content-Type
application/json
Formato JSON para a requisição.
User-Agent
NomeDaSuaAplicacao/1.0
Identifica sua aplicação (ex.: MinhaLoja/1.0
).
Parâmetros da URL
id
string
Sim
ID único do boleto (ex.: 8325a4b3-579c-45df-b475-0ce57df2478d).
Validações:
id
: Deve ser um ID válido retornado pelo endpoint de criação (POST
/v1/charges
).
Resposta
Status:
200 OK
Corpo: JSON com os detalhes do boleto.
Exemplo de Resposta:
{
"id": "8325a4b3-579c-45df-b475-0ce57df2478d",
"status": 2,
"due_date": "2024-12-31",
"grace_period": 15,
"amount": 100.50,
"description": "Payment for services rendered",
"metadata": [
{
"key": "order_id",
"value": "ORD-2024-001"
},
{
"key": "reference",
"value": "REF-12345"
}
],
"payer": {
"name": "João Silva",
"document": "12345678901",
"zip": "01234567",
"street": "Rua das Flores",
"city": "São Paulo",
"state": "SP",
"number": "123",
"neighborhood": "Centro"
},
"fine": 2.5,
"interest": 1.0,
"discount": {
"type": "fixed",
"amount": 10.00,
"limit_date": "2024-12-25"
},
"notification_url": "https://your-webhook.com/notifications",
"customer_code": "CUST-001",
"created_at": "2025-07-23T09:30:00-03:00",
"paid_at": null
}
Campos da Resposta:
id
string
ID único do boleto (ex.: 8325a4b3-579c-45df-b475-0ce57df2478d).
status
number
Status do boleto (1, 2, 3, 4, 5
).
due_date
string
Data de vencimento (formato YYYY-MM-DD
).
grace_period
number
Dias de tolerância após o vencimento (ex.: 15).
amount
number
Valor do boleto em reais (ex.: 100.50 para R$ 100,50).
description
string
Descrição do boleto (máx. 255 caracteres).
metadata
array
Pares chave-valor para dados adicionais (ex.: ID do pedido).
metadata[].key
string
Chave do metadado (ex.: order_id
).
metadata[].value
string
Valor do metadado (ex.: ORD-2024-001
).
payer
object
Dados do pagador.
payer.name
string
Nome completo do pagador (máx. 100 caracteres).
payer.document
string
CPF (11 dígitos) ou CNPJ (14 dígitos).
payer.zip
string
CEP (8 dígitos, sem hífen).
payer.street
string
Rua ou avenida (máx. 200 caracteres).
payer.city
string
Cidade (máx. 100 caracteres).
payer.state
string
UF (2 letras, ex.: SP
).
payer.number
string
Número do endereço (máx. 20 caracteres).
payer.neighborhood
string
Bairro (máx. 100 caracteres).
fine
number
Multa por atraso em percentual (ex.: 2.5 para 2,5%).
interest
number
Juros por dia de atraso em percentual (ex.: 1.0 para 1%).
discount
object
Desconto para pagamento antecipado.
discount.type
string
Tipo de desconto (fixed
ou percentage
).
discount.amount
number
Valor do desconto (em reais para fixed
, ou percentual para percentage
).
discount.limit_date
string
Data limite para o desconto (formato YYYY-MM-DD
).
notification_url
string
URL HTTPS para webhooks (ex.: https://your-webhook.com/notifications
).
customer_code
string
Código interno do cliente (máx. 50 caracteres).
created_at
string
Data de criação do boleto (ISO 8601).
paid_at
string
Data de pagamento do boleto (ISO 8601, ou null
se não pago).
Exemplos de Código
curl -X GET https://sandbox.api.pagou.com.br/v1/charges/8325a4b3-579c-45df-b475-0ce57df2478d \
-H "X-API-KEY: sua_chave_api" \
-H "Content-Type: application/json" \
-H "User-Agent: MinhaLoja/1.0"
Tratamento de Erros
400
Bad Request
ID do boleto malformado.
Verificar formato do id
.
401
Unauthorized
X-API-KEY
inválido ou ausente.
Verificar chave..
404
Not Found
Boleto não existe.
Confirmar ID do boleto.
429
Too Many Requests
Limite de requisições excedido.
Implementar rate limiting e retentativas.
500
Internal Server Error
Erro interno da API.
Tentar novamente e contatar suporte.
Exemplo de Resposta de Erro:
{
"error": "Boleto not found"
}
Boas Práticas Técnicas
Segurança: Armazene
X-API-KEY
em variáveis de ambiente e use HTTPS para todas as requisições.Webhooks como Alternativa: Para atualizações em tempo real, configure o evento
ChargePaid
em vez de consultas frequentes. Veja Webhooks para Interações com Boleto.Testes no Sandbox: Use
https://sandbox.api.pagou.com.br/v1/charges/{id}
para simular consultas sem custos reais.Monitoramento: Registre todas as requisições e respostas em logs, incluindo
id
,status
epaid_at
, para auditoria e depuração.Cache: Considere armazenar respostas em cache (ex.: Redis, com TTL de 5 minutos) para reduzir chamadas à API em sistemas de alto tráfego.
This endpoint return a charge.
Charge ID
Client Identifier
GET /v1/charges/{chargeID} HTTP/1.1
Host: sandbox-api.pagou.com.br
X-API-KEY: YOUR_API_KEY
Accept: */*
text
Last updated