MED (Mecanismo Especial de Devolução)
A rede de segurança do Bacen contra fraude e golpe no Pix: quando a instituição do pagador abre um pedido de devolução, você recebe o aviso no mesmo webhook da transação e trata a contestação sem sair do fluxo.
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
O fluxo em alto nível:
- Transação Pix realizada com sucesso.
- Problema identificado (fraude, erro, cobrança não autorizada).
- Instituição do pagador abre o MED no arranjo, webhook chega com
status: "OPEN". - Banco recebedor é notificado e pode bloquear o valor durante a análise.
- Análise da disputa pelas instituições + regras do Bacen.
- Resultado: aceito (
AGREED, devolve valor) ou rejeitado (DISAGREED, transação permanece válida).
Exemplo de webhook com infração
Exemplo real do payload recebido quando uma transação Pix sofre infração:
{
"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
| 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.
Como reagir quando receber uma infração
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.
if (callback.infraction?.status === 'OPEN') {
await alertOperations({
transactionId: callback.id,
infractionId: callback.infraction.id,
expiresAt: callback.infraction.expiresAt,
reportDetails: callback.infraction.reportDetails,
});
}Investigue
Use GET /user/infractions/{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
| 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 |
| 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
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
Impacto financeiro
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
Não há estorno: o saldo permanece intacto e a transação continua COMPLETED.
Próximos passos
TrueHolder
Garante que o dinheiro só entra ou sai quando o CPF ou CNPJ bate com o titular autorizado, e bloqueia sozinho qualquer movimentação de terceiros, tanto no recebimento quanto no envio.
Tipos de chave Pix
Os cinco tipos oficiais aceitos pelo Bacen, o formato que cada um exige e como a API rejeita na hora, antes de chegar no Bacen, quando a chave vem fora do padrão.