# MED (Mecanismo Especial de Devolução) (/docs/pix-processamento/med)
O **MED (Mecanismo Especial de Devolução)** é um procedimento do Banco
Central que protege usuários Pix em casos de fraude, golpe ou transações
não autorizadas.
Funciona como uma **"rede de segurança"** do arranjo: quando uma
atividade suspeita é identificada, a instituição do pagador abre um
processo formal pedindo o estorno.
Na PayZu, o fluxo do MED é entregue via **webhook**, reutilizando o
mesmo `callbackUrl` da transação. O status da operação original é
atualizado e o objeto `infraction` é inserido no payload.
## Fluxo conceitual do MED [#fluxo-conceitual-do-med]
O fluxo em alto nível:
1. **Transação Pix realizada** com sucesso.
2. **Problema identificado** (fraude, erro, cobrança não autorizada).
3. **Instituição do pagador abre o MED** no arranjo, webhook chega com
`status: "OPEN"`.
4. **Banco recebedor é notificado** e pode bloquear o valor durante a análise.
5. **Análise da disputa** pelas instituições + regras do Bacen.
6. **Resultado**: aceito (`AGREED`, devolve valor) ou rejeitado
(`DISAGREED`, transação permanece válida).
## Exemplo de webhook com infração [#exemplo-de-webhook-com-infração]
Exemplo real do payload recebido quando uma transação Pix sofre
infração:
```json
{
"id": "PAYZU20251123104518DF75D20A8F",
"type": "DEPOSIT",
"status": "COMPLETED",
"serviceFeeCharged": 1,
"amount": 30,
"clientReference": "d2b2a5ed-f1a4-477e-81da-9",
"qrCodeText": "00020101021226870014br.gov.bcb.pix...",
"payerName": "João da Silva",
"payerDocument": "12345678901",
"payerInstitutionName": "PAYZU IP",
"receiverName": "PAYZU LTDA",
"receiverDocument": "123456789010110",
"endToEndId": "E18236120202511231046s1235ee7",
"paidAt": "2025-11-23T10:46:26.986Z",
"createdAt": "2025-11-23T10:45:18.403Z",
"updatedAt": "2025-11-23T10:46:27.346Z",
"callbackUrl": "https://seuwebhook.com",
"infraction": {
"id": "cmide759mb9i3s601bhwf6e",
"protocol": "4dd32924-9b53-4408-af4b-6d3b4d7ac",
"status": "OPEN",
"type": "REFUND_REQUEST",
"reportDetails": "Relato de fraude: transação contestada formalmente pelo pagador",
"reportedBy": "DEBITED_PARTICIPANT",
"analysisResult": null,
"analysisDetails": null,
"reportedAt": "2025-11-24T16:52:15.808Z",
"createdAt": "2025-11-24T17:00:00.490Z",
"updatedAt": "2025-11-24T17:00:00.490Z"
}
}
```
## Campos do objeto `infraction` [#campos-do-objeto-infraction]
| Campo | Tipo | Descrição |
| ----------------- | ---------------------- | -------------------------------------------- |
| `id` | string | Identificador único da infração |
| `protocol` | string | Número de protocolo do provedor de pagamento |
| `status` | InfractionStatus | Status atual da infração |
| `type` | InfractionType | Tipo da infração |
| `reportDetails` | string | Descrição do motivo da disputa |
| `reportedBy` | ReportedBy | Quem reportou a infração |
| `analysisResult` | AnalysisResult \| null | Decisão final (null enquanto pendente) |
| `analysisDetails` | string \| null | Justificativa da decisão |
| `reportedAt` | string | Quando foi reportada |
| `expiresAt` | string \| null | Prazo para resolução |
| `createdAt` | string | Data de criação |
| `updatedAt` | string | Última atualização |
Os valores completos de `status`, `type`, `reportedBy` e `analysisResult` estão no [Glossário](/docs/pix-processamento/glossary).
## Como reagir quando receber uma infração [#como-reagir-quando-receber-uma-infração]
### Detecte o callback [#detecte-o-callback]
Quando o objeto `infraction` chega no payload, dispare alerta interno **imediatamente**. O prazo do Bacen é curto, tipicamente 72h, e silêncio costuma ser interpretado como aceitação.
```ts
if (callback.infraction?.status === 'OPEN') {
await alertOperations({
transactionId: callback.id,
infractionId: callback.infraction.id,
expiresAt: callback.infraction.expiresAt,
reportDetails: callback.infraction.reportDetails,
});
}
```
### Investigue [#investigue]
Use [`GET /user/infractions/{id}`](/docs/pix-processamento/endpoints/infractions/get_infractions_by_id) para detalhes completos da disputa, transação original e prazo. Cruze com seus logs:
* Logs de DICT antes do pagamento (se for saque)
* Quem realizou a operação no seu sistema
* IP, device, sessão do cliente
* Histórico de transações desse `payerDocument`
### Decida: defender ou aceitar [#decida-defender-ou-aceitar]
| Cenário | Decisão recomendada |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Cobrança legítima, tem evidência de entrega de produto/serviço | **Defender** via [`POST /user/infractions/{id}/defenses`](/docs/pix-processamento/endpoints/infractions/post_infractions_defense) |
| Suspeita real de fraude do seu lado (cliente comprometido) | **Aceitar** (não defender). O valor é estornado e o caso fecha. |
| Você não tem evidência | Avaliar caso a caso. Sem defesa, o Bacen tende a aceitar a contestação. |
### Acompanhe até `CLOSED` [#acompanhe-até-closed]
A infração passa por estados (`OPEN → ACKNOWLEDGED/DEFENDED → ANSWERED/WAITING_ADJUSTMENTS → CLOSED`). Cada mudança gera novo callback. O resultado final vem em `analysisResult` quando `status: "CLOSED"`.
## Ciclo de vida completo [#ciclo-de-vida-completo]
## Impacto financeiro [#impacto-financeiro]
### Quando a infração é AGREED [#quando-a-infração-é-agreed]
A transação original (`COMPLETED`) passa por `WAITING_FOR_REFUND`, o valor é debitado do saldo (com tarifa quando cabível) e a transação termina em `REFUNDED`, com webhook de finalização.
### Quando a infração é DISAGREED [#quando-a-infração-é-disagreed]
Não há estorno: o saldo permanece intacto e a transação continua `COMPLETED`.
## Próximos passos [#próximos-passos]