> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pluggoucash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook de transação

> Payload e status enviados nos webhooks de transações

## Webhook de transação

Sempre que ocorre uma mudança de status em uma transação, a Pluggou envia um webhook para todos os endpoints ativos cadastrados na sua conta. Para entender o funcionamento geral dos webhooks (headers, segurança, tempo limite, retentativas e idempotência), consulte o [guia geral de Webhooks](/api-reference/webhooks).

***

## Exemplo de webhook recebido

```bash theme={null}
curl -X POST https://seusite.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Event-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
  -H "User-Agent: Pluggou-Webhook/1.0" \
  -d '{
    "id": "c3d4e5f6-a1b2-7890-cdef-1234567890ab",
    "event_type": "transaction",
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "payment_method": "pix",
        "e2e_id": "E12345678202301011234abcdefghijkl",
        "amount": 10000,
        "platform_tax": 149,
        "liquid_amount": 9851,
        "status": "paid",
        "paid_at": "2026-01-29 14:30:00",
        "created_at": "2026-01-29 14:25:00"
    }
  }'
```

***

## Campos do payload

| Campo                 | Tipo           | Descrição                                                                                             |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `id`                  | string (UUID)  | Identificador único deste evento de webhook.                                                          |
| `event_type`          | string         | Sempre `"transaction"` para webhooks de transação.                                                    |
| `data.id`             | string (UUID)  | Identificador único da transação.                                                                     |
| `data.payment_method` | string         | Método de pagamento utilizado (ex: `"pix"`).                                                          |
| `data.e2e_id`         | string \| null | Identificador end-to-end do PIX gerado pelo banco. Disponível apenas após a confirmação do pagamento. |
| `data.amount`         | integer        | Valor total da transação em centavos.                                                                 |
| `data.platform_tax`   | integer        | Taxa total cobrada pela plataforma em centavos.                                                       |
| `data.liquid_amount`  | integer        | Valor líquido que o usuário receberá em centavos (`amount - platform_tax`).                           |
| `data.status`         | string         | Status atual da transação (veja tabela abaixo).                                                       |
| `data.paid_at`        | string \| null | Data/hora do pagamento no formato `"YYYY-MM-DD HH:mm:ss"`. `null` se ainda não foi pago.              |
| `data.created_at`     | string         | Data/hora de criação da transação no formato `"YYYY-MM-DD HH:mm:ss"`.                                 |

***

## Status possíveis

| Status       | Significado                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `pending`    | Transação criada e aguardando pagamento pelo comprador.                     |
| `paid`       | Pagamento confirmado. O valor líquido foi creditado na carteira do usuário. |
| `failed`     | Pagamento falhou ou foi recusado pela instituição financeira.               |
| `canceled`   | Transação cancelada (expiração ou cancelamento manual).                     |
| `refunded`   | Valor devolvido ao pagador após o pagamento ter sido confirmado.            |
| `chargeback` | Contestação ou disputa aberta pelo pagador (MED, infração, bloqueio).       |