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.

Diferente do webhook de transação, 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`

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

transaction.contested
transaction.contested_reverted
transaction.blocked
transaction.refunded

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.

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
        }
    }
  }'

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.

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
        }
    }
  }'

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.

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
    }
  }'

Enviado quando a contestação é encerrada contra a sua conta e o valor é devolvido ao pagador. A transação passa para o status refunded.

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

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

Guia de implementação

Adquirentes

Transações

Transferências

Webhook de infração