Webhooks

Webhooks para Interações com Pix

Os webhooks da API do Pagou permitem receber notificações assíncronas sobre eventos relacionados a QRCodes Pix, como pagamentos confirmados ou estornos processados. Esta seção detalha os eventos qrcode.completed e qrcode.refunded, suas estruturas de payload, configuração do notification_url.

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 QRCode Pix (via POST /v1/pix ou POST /v1/pix/due). Dois eventos estão disponíveis para Pix:

• qrcode.completed: Notifica quando um QRCode Pix é pago, transitando o status para StatusCompleted.

• qrcode.refunded: Notifica quando um QRCode Pix é estornado, transitando o status para StatusRefunded.

Os webhooks são enviados em formato JSON e requerem um endpoint HTTPS público no lado do cliente para processamento. Cada webhook inclui um campo event_name para identificar o evento e um objeto data com detalhes específicos. A API realiza até 10 tentativas de entrega do webhook, com intervalos exponenciais, até receber uma resposta 200 OK.

Especificações:

• Método: POST

• Content-Type: application/json

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

• Eventos: qrcode.completed, qrcode.refunded.

Configuração do Webhook

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

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 dos Webhooks

Evento: qrcode.completed

Notifica quando um QRCode Pix é pago, indicando que o status mudou para StatusCompleted.

Payload:

{
  "event_name": "qrcode.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "ext-qr-12345",
    "transaction_id": "txn-789012",
    "e2e_id": "E123456789202401151030abcdef123456",
    "amount": 50.00,
    "payer": {
      "name": "João Silva",
      "document": "12345678901",
      "bank": {
        "code": "341",
        "name": "Banco Itaú",
        "agency": "1234",
        "account": "567890",
        "document": "12345678901"
      }
    },
    "description": "Payment for product or service"
  }
}

Campos do Payload:

Campo	Tipo	Descrição
event_name	string	Nome do evento (qrcode.completed).
data	object	Dados do evento.
data.id	string	UUID do QRCode (ex.: 550e8400-e29b-41d4-a716-446655440000).
data.external_id	string	Identificador externo do QRCode .
data.transaction_id	string	ID da transação Pix (ex.: txn-789012).
data.e2e_id	string	ID end-to-end do Pix (ex.: E123456789202401151030abcdef123456).
data.amount	number	Valor pago em reais (ex.: 50.00).
data.payer	object	Dados do pagador.
data.payer.name	string	Nome do pagador (ex.: João Silva).
data.payer.document	string	CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador.
data.payer.bank	object	Dados bancários do pagador.
data.payer.bank.code	string	Código do banco (ex.: 341 para Banco Itaú).
data.payer.bank.name	string	Nome do banco (ex.: Banco Itaú).
data.payer.bank.agency	string	Agência bancária (ex.: 1234).
data.payer.bank.account	string	Conta bancária (ex.: 567890).
data.payer.bank.document	string	CPF ou CNPJ do titular da conta (ex.: 12345678901).
data.description	string	Descrição do pagamento (ex.: Payment for product or service).

Evento: qrcode.refunded

Notifica quando um QRCode Pix é estornado, indicando que o status mudou para StatusRefunded.

Payload:

{
  "event_name": "qrcode.refunded",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "transaction_id": "txn-789012",
    "amount": 25.00,
    "client_code": "CUST-001",
    "description": "Refund requested by customer"
  }
}

Campos do Payload:

Campo	Tipo	Descrição
event_name	string	Nome do evento (qrcode.refunded).
data	object	Dados do evento.
data.id	string	UUID do QRCode (ex.: 550e8400-e29b-41d4-a716-446655440000).
data.transaction_id	string	ID da transação Pix (ex.: txn-789012).
data.amount	number	Valor estornado em reais (ex.: 25.00).
data.client_code	string	Identificador do cliente (ex.: CUST-001, equivalente a customer_id).
data.description	string	Descrição do estorno (ex.: Refund requested by customer).