Webhooks de boleto

Receba eventos de registro e pagamento de boleto e correlacione seus valores.

Entrega e envelope

Configure notification_url ao criar a cobrança. A Pagou envia HTTP POST com JSON para essa URL. Use HTTPS e implemente o recebimento conforme Recebendo webhooks e Autenticação de webhooks.

O envelope usa name para o nome do evento e data para os dados. Não use event_name como nome canônico desse campo. Preserve o corpo bruto até concluir a validação da assinatura.

charge.created

Dados de registro do boleto disponíveis. Payload fictício para compreender o formato, sem dados bancários ou códigos de pagamento utilizáveis:

{
  "name": "charge.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "transaction_id": "fixture-charge",
    "client_code": "550e8400-e29b-41d4-a716-446655440000",
    "payload": {
      "transaction_id": "fixture-charge",
      "bank_emissor": "Instituição de teste",
      "bank_number": "000",
      "bank_agency": "0001",
      "bank_account": "0000000000",
      "bar_code": "CODIGO_DE_BARRAS_DEMONSTRATIVO",
      "line": "LINHA_DIGITAVEL_DEMONSTRATIVA",
      "bank_assignor": "Instituição de teste"
    }
  }
}

charge.paid

Pagamento do boleto confirmado. Payload fictício para compreender o formato, sem dados bancários ou códigos de pagamento utilizáveis:

{
  "name": "charge.paid",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "transaction_id": "fixture-charge-payment",
    "client_code": "550e8400-e29b-41d4-a716-446655440000",
    "amount": {
      "paid": 100.5,
      "original": 100.5
    },
    "paid_in": "boleto",
    "payment_type": "boleto"
  }
}

Campos e correlação

Em charge.created, data.transaction_id e data.client_code usam nomes com underscore. Os dados de registro ficam em data.payload. Campos de Pix vinculado, quando presentes, incluem qrcode_id, data e image.

Em charge.paid, data.amount.paid é o valor pago e data.amount.original é o valor original; os valores podem diferir por encargos ou descontos. Confira data.paid_in e data.payment_type conforme a cobrança. Um evento de registro não é confirmação de pagamento.

Os campos podem receber valores adicionais conforme a cobrança. Valide o subconjunto necessário ao seu fluxo e preserve o payload para auditoria controlada. Dados bancários, documentos e credenciais exigem proteção.

Duplicidade e confirmação

Um evento pode ser reenviado. Valide a assinatura, confira a referência e o valor e registre a entrada de forma durável. Use uma identidade que inclua nome do evento, cobrança e transação; não deduplique apenas pelo ID da cobrança, pois ela pode ter eventos de pagamento e estorno distintos.

Retorne 200 OK após aceitar o evento de forma durável. Não confirme recebimento se a aplicação perdeu o payload. Processe os efeitos financeiros/comerciais uma única vez e reconcilie eventos fora de ordem por consulta.

Leia Recebendo webhooks para o fluxo de entrega e as orientações de tratamento de erros da operação para recuperação. As notificações públicas para a integração são distintas dos webhooks internos do provedor.

Guias relacionados

Primeiros passos · Erros e recuperação · Idempotência e repetição · Recebendo webhooks