Webhooks

Webhooks para Interações com Boletos

Os webhooks da API do Pagou permitem receber notificações assíncronas sobre eventos relacionados a boletos, como a criação ou confirmação de pagamento. Esta seção detalha os eventos charge.created e charge.paid, suas estruturas de payload, configuração do notification_url, autenticação, validação, exemplos de código, tratamento de erros e boas práticas para processar webhooks de forma robusta e segura.

Visão Geral Técnica

A API do Pagou envia notificações via requisições HTTP POST para o notification_url configurado ao criar um boleto (via POST /v1/charges). Os eventos disponíveis para boletos são:

• charge.created: Notifica quando um boleto é criado com sucesso, fornecendo detalhes como código de barras e linha digitável.

• charge.paid: Notifica quando um boleto é pago, indicando que o pagamento foi confirmado.

Os webhooks são enviados em formato JSON e requerem um endpoint HTTPS público no lado do cliente para processamento. A API realiza até 10 tentativas de entrega do webhook, com intervalos exponenciais, até receber uma resposta 200 OK. Se o endpoint não responder com 200 OK, a API reenvia o webhook, exigindo que o processamento seja idempotente.

Especificações:

• Método: POST

• Content-Type: application/json

• URL: Configurada no campo notification_url ao criar o boleto.

• Evento: charge.paid.

• Reenvios: Até 10 tentativas até receber 200 OK.

Configuração do Webhook

1. Definir o notification_url: Ao criar um boleto via POST /v1/charges, inclua o campo notification_url (ex.: https://your-webhook.com/notifications) no corpo da requisição (veja Criando um Boleto).

2. Implementar o endpoint: Crie um endpoint HTTP POST no seu servidor para receber e processar os payloads JSON.

3. Garantir HTTPS: Use um certificado SSL válido para o notification_url.

Estrutura do Webhook

Evento: charge.created

Notifica quando um boleto é criado com sucesso, fornecendo detalhes como código de barras e linha digitável.

Payload:

{
  "name": "charge.created",
  "data": {
    "id": "6bd30949-248e-44c8-8b20-cca8bf6f2686",
    "transactionid": "22bf12b8-77fa-429f-b216-2accf48600eb",
    "clientcode": "6bd30949-248e-44c8-8b20-cca8bf6f2686",
    "payload": {
      "transaction_id": "32bf21d3-55fa-429f-b216-2accf48600ac",
      "bank_emissor": "CELCOIN INSTITUIÇÃO DE PAGAMENTO - SA",
      "bank_number": "1701112",
      "bank_agency": "0001",
      "bank_account": "999911111",
      "bar_code": "99990000000000099990000000000000000000000000",
      "line": "99990000000000000000000000000000000080000009999",
      "bank_assignor": "CELCOIN INSTITUIÇÃO DE PAGAMENTO - SA"
    }
  }
}

Campos do Payload:

Campo	Tipo	Descrição
name	string	Nome do evento (charge.created).
data	object	Dados do evento.
data.id	string	ID do boleto.
data.transactionid	string	ID da transaçã.
data.clientcode	string	Identificador do ID do boleto.
data.payload	object	Detalhes do boleto.
data.payload.transaction_id	string	ID da transação, redundante com data.transactionid.
data.payload.bank_emissor	string	Nome da instituição emissora
data.payload.bank_number	string	Código do banco
data.payload.bank_agency	string	Agência bancária
data.payload.bank_account	string	Conta bancária.
data.payload.bar_code	string	Código de barras do boleto.
data.payload.line	string	Linha digitável do boleto.
data.payload.bank_assignor	string	Nome do cedente.

Evento: charge.paid

Notifica quando um boleto é pago, indicando que o pagamento foi confirmado.

Payload:

{
  "name": "charge.paid",
  "data": {
    "id": "09cd8523-85e8-400f-9c06-3c1950714d6b",
    "transactionid": "a21b0b0f-e142-49e8-a81f-1095527f2ef2",
    "clientcode": "09cd8523-85e8-400f-9c06-3c1950714d6b",
    "amount": {
      "paid": 94.99,
      "original": 94.99
    },
    "paidin": "2025-07-23 08:00:06"
  }
}

Campos do Payload:

Campo	Tipo	Descrição
name	string	Nome do evento (charge.paid).
data	object	Dados do evento.
data.id	string	UUID do boleto (ex.: 09cd8523-85e8-400f-9c06-3c1950714d6b).
data.transactionid	string	ID da transação de pagamento (ex.: a21b0b0f-e142-49e8-a81f-1095527f2ef2).
data.clientcode	string	Identificador do cliente (ex.: 09cd8523-85e8-400f-9c06-3c1950714d6b, equivalente a customer_id).
data.amount	object	Detalhes do valor do boleto.
data.amount.paid	number	Valor pago em reais (ex.: 94.99).
data.amount.original	number	Valor original do boleto em reais (ex.: 94.99).
data.paidin	string	Data e hora do pagamento (formato YYYY-MM-DD HH:MM:SS, ex.: 2025-07-23 08:00:06).
data.paymenttype	string	Tipo de pagamento (ex.: vazio no exemplo, pode ser bank_slip ou similar).

Resposta Esperada:

• Retorne 200 OK para confirmar o recebimento e evitar reenvios (até 10 tentativas pela API).

• Outros códigos (ex.: 400, 401) acionam reenvios pela API do Pagou.