MED (Mecanismo Especial de Devolução)
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
Passe o mouse sobre as caixas para ver o status técnico. Clique para ir direto à seção que detalha cada valor.
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 |
Valores de status (InfractionStatus)
| Valor | Descrição |
|---|---|
WAITING_PSP | Aguardando resposta do provedor |
OPEN | Ativa e em análise |
ACKNOWLEDGED | Reconhecida pela instituição |
DEFENDED | Defesa foi submetida |
ANSWERED | Informações adicionais foram fornecidas |
WAITING_ADJUSTMENTS | Aguardando documentação |
CLOSED | Resolvida com decisão final |
CANCELLED | Cancelada antes da resolução |
Valores de type (InfractionType)
| Valor | Descrição |
|---|---|
REFUND_REQUEST | Pedido de estorno padrão |
FRAUD | Reclamação relacionada à segurança |
REFUND_CANCELLED | Cancelamento de estorno anterior |
Valores de reportedBy
| Valor | Descrição |
|---|---|
DEBITED_PARTICIPANT | Reportada pela instituição do pagador |
CREDITED_PARTICIPANT | Reportada pela instituição do recebedor |
Valores de analysisResult
| Valor | Descrição |
|---|---|
AGREED | Infração aceita: estorno será processado |
DISAGREED | Infração rejeitada: sem estorno |
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
Quando a infração é DISAGREED
TrueHolder
Trava de segurança que valida a titularidade do documento (CPF/CNPJ) antes de processar a transação. Funciona tanto em cash-in (depósito) quanto em cash-out (saque), bloqueando movimentações fora do titular autorizado.
Tipos de chave Pix
Tipos de chave Pix aceitos pela API PayZu, formato esperado de cada um e regras de validação.