Autoatendimento MED (Mecanismo Especial de Devolução)


O Mecanismo Especial de Devolução (MED) é uma funcionalidade do arranjo Pix, regulamentada pelo Banco Central do Brasil (Bacen), destinada exclusivamente a casos de fraude ou golpe.


A solução de autoatendimento desenvolvida, permite que os usuários do PSP Pagador iniciem e acompanhem contestações diretamente pelos canais digitais, promovendo maior autonomia, agilidade e transparência.


Escopo de Aplicação


O MED não se aplica às seguintes situações:

  • Desentendimentos comerciais (ex.: produto com defeito);
  • Erros do usuário (ex.: envio para chave errada);
  • Arrependimento de compra;
  • Transações Pix Saque ou Troco.


Arquitetura da Integração


A jornada de autoatendimento do MED é composta por dois componentes principais:


API REST

  • Criar, consultar e cancelar Notificações de Infração (NIs);

Serviço de Callback (Webhook)

  • Notificações assíncronas sobre mudanças de status nas NIs.


Fluxo Geral da Integração


Ação: PSP envia requisição para iniciar contestação via API;

Resposta síncrona: confirmação de recebimento (202 Accepted);

Processamento assíncrono: MP comunica-se com o arranjo Pix;

Callback: mudanças de status da NI são notificadas via webhook.


1. Criar Notificação de Infração


▶️ Endpoint:


POST /v1/accounts/{accountId}/infraction-reports

  • Inicia o processo de contestação de uma transação suspeita via MED.
  • Requisição é assíncrona e retorna 202 Created.
  • A resposta inclui o infractionReportId, que deve ser armazenado para rastreamento.


Body 



{

  "transactionId": "{{transactionId}}",  // Identificador da transação que será notificada.

  "situationType": "{{situationType}}", // "SCAM", "ACCOUNT_TAKEOVER", "COERCION", "FRAUDULENT_ACCESS", "OTHER"

    "reportDetails": ""  // Se o situationType for "OTHER" esse campo é obrigatório

  }

}


Os possíveis valores do parâmetro situationType são:


Situation Type
Descrição
SCAM
Fui vítima de um golpe e fiz uma transação.
ACCOUNT_TAKEOVER
Outra pessoa transferiu fundos da minha conta sem minha senha e sem meu conhecimento.
COERCION

Fui ameaçado ou tive minha liberdade restringida para ser forçado a fazer uma transação.

FRAUDULENT_ACCESS

Outra pessoa usou minha senha para transferir fundos da minha conta sem minha autorização.

OTHER
Outro cenário não mapeado.



Header


Os valoresdo header são:


Authorization - Token de autenticação

Transaction-Hash - Hash

Idempotency-Id - Codigo de idempotência.


Hash de Autenticação


A requisição exige um hash no header Transaction-Hash calculado assim:


var valoresHash = accountId + transactionId + situationType;

CryptoJS.HmacSHA256(valoresHash, SecretKey);


⚠️ Observações Importantes 

  • O endpoint é idempotente: Requisições repetidas com o mesmo Idempotency-Id não criam novas notificações, retornando a resposta da solicitação original;
  • A confirmação final ocorre via callback.


2. Consultar Notificações de Infração


▶️ Endpoint:


GET /v1/accounts/{accountId}/infraction-reports

  • Retorna uma lista paginada das NIs criadas pelo PSP Pagador.
  • Restringe a busca aos últimos 90 dias e ao mesmo cliente.


Params


Os parâmetros possíveis são:


pageSize // Quantidade de itens por página 

pageNumber // Número da página

creationDateStart // Data inicio do período em formato YYYY-MM-DD da criação da notificação

creationDateEnd // Data final do período em formato YYYY-MM-DD da criação da notificação

status // Valores possíveis: OPEN, ACKNOWLEDGED, CLOSED e CANCELLED

analysisResult // Valores possíveis: AGREED e DISAGREED

infractionReportId // Identificador da notificação


*Os campos em negrito são obrigatórios.


Regras de negócio aplicadas:

  • Escopo limitado ao PSP Pagador (DEBITED_PARTICIPANT);
  • Lista NIs criadas por qualquer canal de atendimento do PSP;
  • Não exibe dados anteriores à ativação do autoatendimento.


3. Cancelar Notificação de Infração


▶️ Endpoint:


POST /v1/accounts/{accountId}/infraction-reports/{infractionReportId}/cancellations

  • Solicita o cancelamento de uma NI existente (por iniciativa do PSP Pagador).
  • Processo assíncrono, com retorno 202 Accepted.
  • Confirmação final via callback.


Cancelamento não permitido se:

  • A NI já estiver com dictStatus: "CANCELLED";
  • Ou com analysisResult: "DISAGREED".


Header


Os valoresdo header são:


Authorization - Token de autenticação

Transaction-Hash - Hash

Idempotency-Id - Codigo de idempotência.


Hash de Autenticação


A requisição exige um hash no header Transaction-Hash calculado assim:


var valoresHash = accountId +  infractionReportId;

CryptoJS.HmacSHA256(valoresHash, SecretKey);



4. Derivação de Status de Negócio


O status exibido ao usuário final é derivado da combinação entre dictStatus e analysisResult. A tabela abaixo resume a lógica:


dictStatus
analysisResult
Status final
Nulo
Nulo
EM ANÁLISE
OPEN / ACKNOWLEDGED
Nulo
EM ANÁLISE
CLOSED
AGREED
APROVADA
CLOSED
DISAGREED
REJEITADA
CANCELLED
Qualquer valor
CANCELADA


5. Configurar o Serviço de Callback


Para gerenciar a natureza assíncrona do MED, o Sistema de Meios de Pagamento notifica o PSP participante sobre as mudanças de estado no ciclo de vida de uma Notificação de Infração (NI).


Esses callbacks são fundamentais para manter o status atualizado sem a necessidade de polling contínuo.


Requisitos técnicos:

  • O sistema do PSP deve expor um endpoint HTTP do tipo POST;
  • O endpoint deve ser seguro e publicamente acessível;
  • A comunicação é feita via payload JSON, enviado a cada evento relevante.


Eventos e Gatilhos


O Sistema envia callbacks nos seguintes marcos de negócio:


EventoDescrição
OPENConfirmação de que a NI foi aberta e registrada no DICT
CLOSEDResultado da análise da notificação (AGREED ou DISAGREED)
CANCELLEDConfirmação de cancelamento a pedido do pagador
ERRORNotificação de falha crítica no processamento da NI


Exemplo de Payload 


{

  "callbackType": "MED",

  "accounts": [

    "xxx555-aaa44s"

  ],

  "payloadMessage": {

    "infractionReportId": "f25ba892-95e0-11ea-bb37-0242ac130002",

    "spiInfractionReportId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",

    "dictId": "c1d3e7a9-6b8f-4a2d-8c1e-9f0a3b4c5d6e",

    "status": "CLOSED",

    "dictStatus": "CLOSED",

    "endToEndId": "E12345678202508281030abcdef12345",

    "transactionId": "E12345678202508281030abcdef12345",

    "totalAmount": 1250.75,

    "receiverName": "NOME COMPLETO DO RECEBEDOR",

    "situationType": "SCAM",

    "reportDetails": "Cliente informa que foi vítima de um golpe de falso investimento.",

    "analysisResult": "AGREED",

    "analysisDetails": "Análise concluída, fraude confirmada pela contraparte.",

    "pspResponseDeadline": null,

    "dataTimeEvent": "2025-08-28T14:39:20Z"

  },

  "version": "v2"

}


OBS: A versão liberada no ambiente de homologação ainda está em fase de implementação e neste sentido, alguns fluxos poderão estar incompletos (finalização de cancelamento de notificação e envio de callbacks).


Suporte


Para dúvidas ou acompanhamento de chamados, acesse: Portal de Suporte