Autoatendimento MED 2.0 (Mecanismo Especial de Devolução)
O MED 2.0 é a evolução do sistema de segurança do Pix, regulamentada pelo Banco Central do Brasil. A grande novidade é o rastreamento multicamadas, que permite identificar o fluxo do dinheiro em até cinco camadas subsequentes, combatendo a pulverização de valores em contas "laranjas".
Até o dia 10 de maio de 2026 será necessária a disponibilização dessa funcionalidade em PRODUÇÃO. Com isso, é imprescindível que os aplicativos disponibilizados aos usuários finais estejam em conformidade com a legislação vigente.
Escopo de Aplicação
O MED 2.0 é exclusivo para casos de fraude, golpe ou coação. Não se aplica a:
- Desacordos comerciais ou arrependimento de compra.
- Erros de digitação (envio para chave errada).
- Transações com mais de 80 dias da data original.
Arquitetura da Integração
A jornada utiliza uma API REST assíncrona. O diferencial do MED 2.0 é que o rastreamento e bloqueio nas diversas contas da cadeia ocorrem de forma automatizada via DICT.
1. Criar Recuperação de Fundos
Este endpoint inicia o processo de rastreamento e bloqueio automático de uma transação suspeita.
▶️ Endpoint:
POST /v1/accounts/{accountId}/funds-recoveries
Request Body (JSON):
{
"transactionId": "{{transactionId}}",
"situationType": "{{situationType}}",
"reportDetails": "Detalhes da ocorrência", // Obrigatório se situationType for "OUTRO"
"complaintCreationTimeUtc": "2026-02-10T08:45:00Z" // Opcional
"trackgraph": {
"maxhops": 1 // Obrigatório ser enviado com o valor 1
}
}
Tipos de Situação (Situation Types):
Esta tabela define os códigos que devem ser enviados no corpo da requisição (situationType) ao criar uma solicitação de recuperação de fundos:
| Valor (Enum) | Descrição do Cenário |
| SCAM | O usuário foi enganado por um golpista e realizou a transação voluntariamente (Engenharia Social). |
| ACCOUNT_TAKEOVER | Outra pessoa transferiu fundos da conta do cliente sem o uso de senha e sem o seu conhecimento. |
| COERCION | O usuário foi ameaçado ou teve sua liberdade restringida para ser forçado a realizar a transação. |
| FRAUDULENT_ACCESS | Um golpista utilizou a senha do cliente para transferir fundos sem autorização. |
| OTHER | Outro tipo de golpe não mapeado nos campos anteriores (exige preenchimento de reportDetails). |
Hash de Autenticação (Header: Transaction-Hash):
Para garantir a integridade da requisição, o cabeçalho Transaction-Hash deve ser gerado seguindo a lógica abaixo, presente nos scripts de pré-requisição da collection:
| Parâmetro | Regra de Cálculo |
| Lógica de Concatenação | accountId + transactionId |
| Algoritmo | HMAC-SHA256 |
| Exemplo de Script (Postman) | CryptoJS.HmacSHA256(accountId + transactionId, SecretKey); |
⚠️ Observações Importantes
|
2. Consultar Recuperação de Fundos
Permite listar as solicitações do cliente para acompanhar o progresso do rastreamento multicamadas.
▶️ Endpoint:
GET /v1/accounts/{accountId}/funds-recoveries
Principais Parâmetros de Filtro:
- pageSize / pageNumber: Paginação obrigatória.
- creationDateStart / creationDateEnd: Período de criação.
- status: Filtra pelo estado atual (ex: AGUARDANDO_ANALISE, ANALISADO).
3. Cancelar Recuperação de Fundos
Permite ao PSP Pagador interromper uma solicitação. O cancelamento só é permitido se o status for AGUARDANDO_ANALISE ou ANALISADO. Não pode ser cancelado se já estiver CONCLUIDO ou REJEITADO.
▶️ Endpoint:
POST /v1/accounts/{accountId}/funds-recoveries/{fundsRecoveryId}/cancellations
Hash de Autenticação (Header: Transaction-Hash): CryptoJS.HmacSHA256(accountId + fundsRecoveryId, SecretKey);
4. Mapeamento de Status (Visão do Usuário)
Diferente da versão 1.0, o MED 2.0 utiliza um campo de status unificado para simplificar a experiência do cliente:
| Status da API | Significado para o Cliente |
| CREATED | A RECUPERAÇÃO FOI CRIADA |
| ERROR | UM ERRO OCORREU NA CRIAÇÃO DA RECUPERAÇÃO |
| AWAITING_ANALYSIS | NOTIFICAÇÃO DE INFRAÇÃO CRIADA; O PSP RECEBEDOR ESTA ANALISANDO |
| ANALYSED | A RECUPERAÇÃO DE FUNDOS FOI ANALISADA |
| REFUNDING | EM PROCESSAMENTO (Recuperação iniciada) |
| REJECTED | REJEITADA (Fraude não confirmada ou saldo zerado) |
| COMPLETED | APROVADA (Valor total ou parcial recuperado) |
| AWAITING_CANCELLING | A RECUPERAÇÃO DE FUNDOS ESTA SENDO CANCELADA |
| CANCELLED | CANCELADA |
5. Configuração de Callback (Webhook)
O sistema envia notificações assíncronas sempre que houver uma mudança de status relevante ou quando um valor for efetivamente recuperado de uma das camadas da cadeia.
Campos importantes no Payload:
- fundsRecoveryId: Identificador único da solicitação.
- effectiveRefundAmount: Valor que foi efetivamente recuperado (pode ser parcial se o golpista já tiver sacado parte do montante).
- status: Estado atual da recuperação conforme a tabela acima.
Suporte
Para dúvidas ou acompanhamento de chamados, acesse: Portal de Suporte