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

Cabeçalho
Valor
Descrição

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

Parâmetro
Tipo
Obrigatório
Descrição

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:

Campo
Tipo
Descrição

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

Código HTTP
Descrição
Possível Causa
Solução

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 e paid_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.

Get a Charge

get

This endpoint return a charge.

Authorizations
Path parameters
chargeIDanyRequired

Charge ID

Header parameters
User-AgentanyOptional

Client Identifier

Responses
200
OK
application/json
Responsestring
get
GET /v1/charges/{chargeID} HTTP/1.1
Host: sandbox-api.pagou.com.br
X-API-KEY: YOUR_API_KEY
Accept: */*
text

Last updated