Disputas — Mecanismo Especial de Devolução (MED)
O MED é o processo pelo qual o pagador de um PIX pede a devolução do valor, normalmente por suspeita de fraude. Quando uma disputa é aberta contra uma conta sua, você recebe um webhook, tem 48 horas para apresentar a defesa do correntista, e a CorpX conduz a análise e responde ao arranjo dentro do prazo regulamentar.
Três coisas definem como este módulo funciona, e vale saber delas antes de integrar:
- Quem decide é a análise da CorpX, dentro das regras do arranjo. Não existe rota para devolver o PIX, liberar saldo ou recusar a devolução. O que você faz aqui é registrar a versão do correntista, com texto e anexos, e responder a pedidos de esclarecimento.
- A API mostra o status da análise, não o do liquidante.
reviewStatusdiz em que etapa a disputa está do lado da CorpX e o que você pode fazer nela. O status que o liquidante comunica continua chegando pelo webhookpix.med.updated, como sempre. - O valor fica retido enquanto a disputa corre. Ao receber a disputa, a
CorpX retém o valor na conta até o saldo disponível;
lockStatuselockedAmountmostram isso. Se a devolução não acontecer, o valor é liberado; se acontecer, sai desse saldo retido.
As etapas de uma MED
Nada é rejeitado automaticamente pelo tempo. Vencer o prazo da defesa não
encerra a disputa nem gera devolução por si: a análise segue, sem a versão do
correntista. Monitore clientAnswerDeadline e infoDueAt — ou o painel, que
avisa quando falta menos de 12 horas.
MED aberta pela CorpX (direction)
A lista traz dois tipos de disputa, separados por direction:
received— aberta contra a conta pelo banco do pagador. Segue o fluxo acima.opened— aberta pela CorpX em nome do correntista, porque o PIX contestado saiu desta conta. Não há defesa nem prazo (clientAnswerDeadlinenulo), não há retenção de saldo, e a análise fica emawaiting_resultaté o banco liquidante decidir.answer,messages,submite os anexos respondem409 med_opened_by_us.
Num PIX entre duas contas da CorpX, a disputa na conta que recebeu o valor é
received, com defesa e retenção como qualquer outra.
partnerStatus (OPEN, PENDING_DECISION, ACCEPTED, REJECTED,
CANCELED) é a situação no banco liquidante pelo último webhook, e
lastUpdatedAt diz quando ela chegou. Na MED opened, é o que mostra o
andamento.
Status da análise
Enquanto a conta estiver bloqueada pela execução (in_execution), as
operações financeiras dela respondem 403 account_blocked. A devolução do PIX
em disputa é feita pela CorpX e não passa por esse bloqueio.
Recebendo disputas por webhook
Três eventos. Assine os três.
O status em pix.med.opened e pix.med.updated é o estado no liquidante
no instante daquele evento. Reentrega do mesmo estado não gera evento novo,
e evento atrasado é descartado — você não vê a disputa voltar no tempo.
reasonCode é o código do arranjo, repassado como vem
(unauthorized-transaction, fraud, scam-or-fraud, …). Não normalizamos
para um enum nosso.
O relato traz o banco do reclamante, não o nome ou documento dele. Essa informação não é disponibilizada ao recebedor.
pix.med.review.updated
data é sempre o retrato atual da disputa; reason diz o que acabou de
acontecer. Você não precisa acumular eventos para saber onde ela está.
Consultando disputas
Paginada por limit (máximo 200) e offset. Não há filtro por status.
A lista traz só as disputas em que esta conta está: a MED é vinculada à
conta que o banco liquidante identifica no webhook, não ao CPF/CNPJ do
titular. Um titular com mais de uma conta vê cada disputa apenas na conta
do PIX contestado; consultar a MED por outra conta do mesmo titular responde
404 med_not_found.
transactionId liga a disputa ao lançamento do PIX no seu extrato, quando ele
existe na plataforma. Depois de responder, answered fica true e aparecem
answeredAt, answerResult e answer (a justificativa que você enviou).
Detalhe de uma disputa
Tudo da listagem mais a linha do tempo, as mensagens trocadas, os anexos com
downloadUrl e o que está habilitado agora:
events é a linha do tempo visível ao correntista. steps lista, em texto, o
que a CorpX já executou na devolução (conta bloqueada, valor devolvido, conta
liberada) — aparece a partir de in_execution. Os quatro can* dizem o que
está habilitado neste instante; use-os em vez de deduzir pelo status.
Anexando evidências
Anexo é aceito enquanto a disputa está em awaiting_defense (antes do
answer) ou em info_requested. Fora disso a rota responde 409 med_not_writable: o pacote já seguiu.
São três passos. O arquivo vai direto do seu lado para o armazenamento, sem passar pelo corpo da nossa API.
1. Peça a URL de upload
sizeBytes é o tamanho real do arquivo, não uma estimativa: ele entra na
assinatura da URL. Declarar um número e enviar outro faz o armazenamento
recusar o PUT.
2. Envie o arquivo na URL assinada
PUT direto na uploadUrl, com o mesmo Content-Type e exatamente os
sizeBytes que você declarou. Sem cabeçalho de autenticação nosso — a
assinatura já autoriza, e um header a mais faz o armazenamento recusar.
3. Registre o anexo
Sem este passo o arquivo fica no armazenamento e não entra na defesa: é o
registro que liga o binário à disputa. Tipo e tamanho são conferidos de novo
aqui, com os mesmos limites e os mesmos errorCode da tabela abaixo — as duas
chamadas são independentes. messageId é opcional: em info_requested, liga
o anexo à mensagem que o explica.
Todo upload passa por verificação de tipo real, antivírus e sanitização antes
de ficar disponível — alguns segundos. scanStatus acompanha isso:
PENDING em processamento, APPROVED liberado, REJECTED recusado (com
scanReason). Arquivo recusado não segue com a defesa.
Limites
Listando o que está anexado
Devolve os anexos da disputa com downloadUrl assinada (curta duração) para
cada um que passou na verificação. Com ?evidenceId= retorna apenas um. O
mesmo conteúdo vem em evidences no detalhe.
Respondendo a uma disputa
Resposta 202:
A defesa e os anexos entram na análise e reviewStatus passa a
pending_review. Responder é registrar a versão do correntista, não encerrar
o caso: a decisão vem depois, pelo webhook.
Erros específicos desta rota:
Respondendo a um pedido de esclarecimento
Em info_requested, a pergunta da análise está em infoRequest.message do
detalhe e no webhook. O correntista responde com mensagens e anexos e você
fecha o pacote com submit.
Resposta 201 com messageId. Anexos ligados à mensagem vão em
evidence/add com esse messageId. Até 2.000 caracteres por mensagem; a
rota só aceita em info_requested (409 med_not_writable fora disso).
Sem corpo. Devolve 202 com o detalhe e reviewStatus: pending_review. Se
não houve mensagem nem anexo novo desde o pedido, responde 422 med_info_missing — enviar vazio não ajuda a análise.
Erros do módulo
Taxa de MED
Devolve os contadores de prazo e a série diária da taxa:
A listagem equivalente por tenant é
GET /v1/backoffice/tenants/{tenantId}/meds, com os filtros accountId,
limit e offset.
Faixas de referência
Referência operacional, usada no painel e no acompanhamento comercial. Nenhum erro ou bloqueio decorre automaticamente delas — ações automáticas por taxa se configuram em Políticas e Regras.
Políticas de MED
Veja Políticas e Regras para:
- Auto-block: reter saldo automaticamente em disputa acima de um valor.
- Taxa máxima (seção
med): teto de proporção MED/PIX recebido por conta, em janela móvel, que bloqueia a saída da conta. Tem um segundo teto, mais baixo, só para MEDs críticas — relato do reclamante com termos de golpe ou apostas, ou motivoscam-or-frauddo liquidante.