# 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 <mark style="color:orange;">`qrcode.completed`</mark> e <mark style="color:orange;">`qrcode.refunded`</mark>, 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 <mark style="color:green;">`POST`</mark>` ``/v1/pix` ou <mark style="color:green;">`POST`</mark>` ``/v1/pix/due`). Dois eventos estão disponíveis para Pix:

* **qrcode.completed**: Notifica quando um QRCode Pix é pago, transitando o status para <mark style="color:orange;">`StatusCompleted`</mark>.
* **qrcode.refunded**: Notifica quando um QRCode Pix é estornado, transitando o status para <mark style="color:orange;">`StatusRefunded`</mark>.

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**: <mark style="color:green;">`POST`</mark>
* **Content-Type**: `application/json`
* **URL**: Configurada no campo `notification_url` ao criar o QRCode.
* **Eventos**: <mark style="color:orange;">`qrcode.completed`</mark>, <mark style="color:orange;">`qrcode.refunded`</mark>.

### Configuração do Webhook

1. **Definir o** `notification_url`: Ao criar um QRCode via <mark style="color:green;">`POST`</mark>` ``/v1/pix` ou <mark style="color:green;">`POST`</mark>` ``/v1/pix/due`, inclua o campo `notification_url` (ex.: <https://your-webhook.com/notifications>) no corpo da requisição (veja [Criando um QRCode ](https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-pix/criando-um-qrcode-imediato)ou [Criando um QRCode com Vencimento](https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-pix/criando-um-qrcode-com-vencimento)).
2. **Implementar o endpoint**: Crie um endpoint HTTP <mark style="color:green;">`POST`</mark> 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 <mark style="color:orange;">`StatusCompleted`</mark>.

**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).             |