> ## 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 infração

> Payload e eventos enviados nos webhooks de infração (MED) de transações

## Webhook de infração

Quando uma transação PIX recebe uma infração (MED – Mecanismo Especial de Devolução) ou tem seu andamento alterado, a Pluggou envia um webhook para todos os endpoints ativos cadastrados na sua conta para o tipo **Transações**. Para entender o funcionamento geral dos webhooks (headers, segurança, tempo limite e idempotência), consulte o [guia geral de Webhooks](https://docs.pluggoucash.com/api-reference/webhooks.md).

> [!NOTE]
>
> Diferente do [webhook de transação](https://docs.pluggoucash.com/api-reference/transactions/webhooks.md), em que `event_type` é sempre `"transaction"`, nos webhooks de infração o campo `event_type` identifica **qual etapa da infração** ocorreu. Use esse campo para decidir como tratar cada evento.

***

## Eventos enviados

| `event_type` | Quando é enviado | `data.status` resultante |
| - | - | - |
| `transaction.contested` | Uma contestação (MED) foi aberta para a transação. | `chargeback` |
| `transaction.contested_reverted` | A contestação foi encerrada **a favor** da sua conta. O valor é mantido. | `paid` |
| `transaction.blocked` | O valor líquido da transação foi bloqueado de forma cautelar durante a análise. | status atual da transação |
| `transaction.refunded` | A contestação foi encerrada **contra** a sua conta. O valor foi devolvido ao pagador. | `refunded` |

> [!WARNING]
>
> O status `chargeback`, por si só, **não gera bloqueio nem desconto do saldo** da sua conta. Ele apenas indica que existe uma contestação em andamento para a transação.
>
> O saldo em conta só sofre desconto em dois casos:
>
> * quando é gerado um **bloqueio cautelar** (evento `transaction.blocked`), que retém o valor líquido da transação durante a análise; ou
> * quando ocorre o **reembolso** da transação (evento `transaction.refunded`), com a devolução do valor ao pagador.

***

## Exemplos por evento

> [tab] transaction.contested
>
> Enviado no momento em que uma contestação é aberta para a transação. O status da transação passa para `chargeback` e o payload inclui o bloco `data.med` com a categoria, a justificativa informada pelo pagador e a taxa de defesa cobrada.
>
> ```bash theme={null}
> curl -X POST https://seusite.com/webhook \
>   -H "Content-Type: application/json" \
>   -H "X-Webhook-Event-ID: 2f5c1a7e-9d3b-4c8a-b1e6-7a0d4f9c2b31" \
>   -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
>   -H "User-Agent: Pluggou-Webhook/1.0" \
>   -d '{
>     "id": "afc36e2f-6664-4564-b77c-3b56487832dc",
>     "event_type": "transaction.contested",
>     "data": {
>         "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
>         "payment_method": "pix",
>         "e2e_id": "E12345678202301011234abcdefghijkl",
>         "amount": 25000,
>         "platform_tax": 150,
>         "liquid_amount": 24850,
>         "status": "chargeback",
>         "paid_at": "2026-01-29 14:30:00",
>         "created_at": "2026-01-29 14:25:00",
>         "med": {
>             "category": "undelivered_product",
>             "category_label": "Produto não entregue",
>             "justification": "Comprei um produto e não recebi.",
>             "defense_tax": 500
>         }
>     }
>   }'
> ```

> [tab] transaction.contested\_reverted
>
> Enviado quando a contestação é encerrada a favor da sua conta. A transação volta ao status `paid` e o valor líquido permanece disponível. O payload também traz o bloco `data.med` com os dados da contestação encerrada.
>
> ```bash theme={null}
> curl -X POST https://seusite.com/webhook \
>   -H "Content-Type: application/json" \
>   -H "X-Webhook-Event-ID: 8b1d4e2a-6c7f-4a90-9e3d-5f2b8c1a7d64" \
>   -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
>   -H "User-Agent: Pluggou-Webhook/1.0" \
>   -d '{
>     "id": "259e317a-e949-4660-8539-88992e801baf",
>     "event_type": "transaction.contested_reverted",
>     "data": {
>         "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
>         "payment_method": "pix",
>         "e2e_id": "E12345678202301011234abcdefghijkl",
>         "amount": 25000,
>         "platform_tax": 150,
>         "liquid_amount": 24850,
>         "status": "paid",
>         "paid_at": "2026-01-29 14:30:00",
>         "created_at": "2026-01-29 14:25:00",
>         "med": {
>             "category": "undelivered_product",
>             "category_label": "Produto não entregue",
>             "justification": "Comprei um produto e não recebi.",
>             "defense_tax": 500
>         }
>     }
>   }'
> ```

> [tab] transaction.blocked
>
> Enviado quando o valor líquido da transação é bloqueado de forma cautelar enquanto a contestação é analisada. O status da transação **não muda** neste evento; o payload inclui `data.block_uuid` e `data.blocked_amount` com o valor retido.
>
> ```bash theme={null}
> curl -X POST https://seusite.com/webhook \
>   -H "Content-Type: application/json" \
>   -H "X-Webhook-Event-ID: c4a9f0e3-1b2d-4f67-8a5c-9d0e3b6f2a18" \
>   -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
>   -H "User-Agent: Pluggou-Webhook/1.0" \
>   -d '{
>     "id": "1a30137d-856b-4761-a1f2-57ee49da8e49",
>     "event_type": "transaction.blocked",
>     "data": {
>         "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
>         "payment_method": "pix",
>         "e2e_id": "E12345678202301011234abcdefghijkl",
>         "amount": 25000,
>         "platform_tax": 150,
>         "liquid_amount": 24850,
>         "status": "chargeback",
>         "paid_at": "2026-01-29 14:30:00",
>         "created_at": "2026-01-29 14:25:00",
>         "block_uuid": "ba3de179-566c-4d96-b6eb-f77bbdf4ea63",
>         "blocked_amount": 24850
>     }
>   }'
> ```

> [tab] transaction.refunded
>
> Enviado quando a contestação é encerrada contra a sua conta e o valor é devolvido ao pagador. A transação passa para o status `refunded`.
>
> ```bash theme={null}
> curl -X POST https://seusite.com/webhook \
>   -H "Content-Type: application/json" \
>   -H "X-Webhook-Event-ID: 7e2b9c4d-0f1a-4e83-b6d5-3c8a1f9e0b72" \
>   -H "X-Webhook-Code: whk_a8Kd92mNx7Pq3rT5vW1yZ0bC4eF6gH8jL0mN2pR4tV6x" \
>   -H "User-Agent: Pluggou-Webhook/1.0" \
>   -d '{
>     "id": "3efbcd08-4ee0-44f0-94b4-9518427606dd",
>     "event_type": "transaction.refunded",
>     "data": {
>         "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
>         "payment_method": "pix",
>         "e2e_id": "E12345678202301011234abcdefghijkl",
>         "amount": 25000,
>         "platform_tax": 150,
>         "liquid_amount": 24850,
>         "status": "refunded",
>         "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 | Tipo do evento de infração (veja a tabela [Eventos enviados](#eventos-enviados)). |
| `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. |
| `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 da transação em centavos (`amount - platform_tax`). |
| `data.status` | string | Status da transação após o evento (`chargeback`, `paid` ou `refunded`). |
| `data.paid_at` | string \| null | Data/hora do pagamento no formato `"YYYY-MM-DD HH:mm:ss"`. |
| `data.created_at` | string | Data/hora de criação da transação no formato `"YYYY-MM-DD HH:mm:ss"`. |

### Campos adicionais em `transaction.contested` e `transaction.contested_reverted`

| Campo | Tipo | Descrição |
| - | - | - |
| `data.med.category` | string | Chave da categoria da contestação (veja [Categorias de contestação](#categorias-de-contestacao)). |
| `data.med.category_label` | string | Nome da categoria em português. |
| `data.med.justification` | string | Justificativa informada pelo pagador ao abrir a contestação. |
| `data.med.defense_tax` | integer | Taxa de defesa cobrada pela contestação, em centavos. `0` quando não há cobrança. |

### Campos adicionais em `transaction.blocked`

| Campo | Tipo | Descrição |
| - | - | - |
| `data.block_uuid` | string (UUID) | Identificador do bloqueio cautelar. |
| `data.blocked_amount` | integer | Valor retido em centavos (corresponde ao valor líquido da transação). |

***

## Categorias de contestação

| `category` | `category_label` | Descrição |
| - | - | - |
| `invasion` | Invasão | Conta ou aplicativo do pagador invadido; acesso não autorizado. |
| `gov` | Gov | Cobrança indevida relacionada a órgãos ou serviços governamentais. |
| `concurso` | Concurso | Concursos e taxas de inscrição em concursos. |
| `ticket` | Ingresso | Ingressos para shows, eventos e espetáculos. |
| `child_pornography` | CP | Conteúdo ilegal envolvendo menores. |
| `clone` | Clone | Compra em site ou página falsa/clonada de marca conhecida. |
| `airfare` | Passagem aérea | Passagens e bilhetes aéreos. |
| `undelivered_product` | Produto não entregue | Produto ou serviço pago e não entregue. |
| `other` | Outro | Demais casos sem enquadramento nas categorias acima. |

***

## Boas práticas

> [!WARNING]
>
> Trate os eventos de infração de forma **idempotente**: use o header `X-Webhook-Event-ID` (ou o campo `id` do payload) para ignorar eventos já processados e nunca presuma a ordem de chegada. Baseie a situação final da transação sempre no `data.status` do evento mais recente.

* Ao receber `transaction.contested`, sinalize a venda como em disputa no seu sistema e evite liberar o produto/serviço até o encerramento.
* Ao receber `transaction.contested_reverted`, a venda pode voltar ao fluxo normal: o valor continua creditado na sua carteira.
* Ao receber `transaction.refunded`, registre o estorno da venda: o valor foi devolvido ao pagador.
* Use `data.med.category` para automatizar regras internas (ex.: revisar pedidos de uma mesma categoria recorrente).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.