# 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.: ) no corpo da requisição (veja [Criando um QRCode ](/integracao-com-a-api/meio-de-pagamento-pix/criando-um-qrcode-imediato.md)ou [Criando um QRCode com Vencimento](/integracao-com-a-api/meio-de-pagamento-pix/criando-um-qrcode-com-vencimento.md)).
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**:
```json
{
"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**:
```json
{
"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). |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-pix/webhooks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.