Skip to navigation

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. reviewStatus diz 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 webhook pix.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; lockStatus e lockedAmount mostram isso. Se a devolução não acontecer, o valor é liberado; se acontecer, sai desse saldo retido.

As etapas de uma MED

EtapareviewStatusQuem agePrazo
Defesaawaiting_defenseCorrentista, via você48 h da abertura (clientAnswerDeadline)
Análisepending_reviewCorpXAté 7 dias da abertura, prazo do arranjo
Esclarecimentoinfo_requestedCorrentista, via você24 h do pedido (infoDueAt), limitado ao prazo da análise
Execuçãoin_executionCorpXDevolução em até 96 h após a decisão
Aguardando saldoawaiting_fundsCorpXEnquanto houver valor a devolver; novas devoluções conforme o saldo entrar
Encerradarefunded ou refused——

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 (clientAnswerDeadline nulo), não há retenção de saldo, e a análise fica em awaiting_result até o banco liquidante decidir. answer, messages, submit e os anexos respondem 409 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

reviewStatusSignificadoO que você pode fazer
awaiting_defenseDisputa aberta, aguardando a defesa do correntista.Anexar evidências e responder (answer).
pending_reviewDefesa recebida (ou prazo vencido); a CorpX analisa.Acompanhar.
info_requestedA CorpX pediu esclarecimento; a pergunta está em infoRequest.message.Enviar mensagens e anexos, depois submit.
in_executionDevolução decidida; a CorpX bloqueia a conta, devolve o PIX e libera a conta.Acompanhar pelo webhook.
awaiting_fundsO saldo não cobriu o valor; o restante fica retido e é devolvido conforme entrar.Acompanhar.
refundedDevolução concluída. refundPartial indica se foi parcial.—
refusedDevolução recusada; valor liberado na conta.—
awaiting_resultSó em direction: opened: a CorpX abriu a disputa e aguarda o banco liquidante.Acompanhar partnerStatus.
lockStatusSignificado
pendingRetenção ainda não efetivada.
lockedValor retido; lockedAmount diz quanto.
failedA retenção não foi possível no momento; a CorpX reavalia.
unlockedValor liberado.
ausenteDisputa anterior à retenção automática.

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.

EventoQuando
pix.med.openedAbertura da disputa.
pix.med.updatedCada mudança de status que o liquidante comunicar.
pix.med.review.updatedCada passo da análise da CorpX: defesa recebida, esclarecimento pedido, decisão, bloqueios, devoluções, encerramento.
{
"id": "pix-med-opened-204cc938-da3d-4f04-baf3-0b2e6a2f1283-OPEN",
"type": "pix.med.opened",
"occurredAt": "2026-02-18T19:34:14.000000000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-suaempresa",
"accountId": "773107de-...",
"data": {
"medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
"tenantId": "tenant-suaempresa",
"accountId": "773107de-...",
"originalEndToEnd": "E303062942026021812490000005QLMv",
"amount": 1000.00,
"reasonCode": "unauthorized-transaction",
"claimMessage": "Não reconheço esta transação",
"openedAtIso": "2026-02-18T19:34:14.000000000Z",
"clientAnswerDeadlineIso": "2026-02-20T19:34:14.000000000Z",
"status": "OPEN"
}
}

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

{
"id": "pix-med-review-204cc938-...-info_requested-1771598551000",
"type": "pix.med.review.updated",
"occurredAt": "2026-02-20T14:02:31Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-suaempresa",
"accountId": "773107de-...",
"data": {
"medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
"accountId": "773107de-...",
"reason": "info_requested",
"reviewStatus": "info_requested",
"round": null,
"decision": null,
"decisionMessage": null,
"infoRequest": { "message": "Envie o comprovante de entrega com o rastreio." },
"infoDueAt": "2026-02-21T14:02:31Z",
"lockStatus": "locked",
"lockedAmount": 1000.00,
"refund": null,
"refundedTotal": 0,
"remaining": 1000.00,
"refundPartial": false
}
}

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á.

reasonO que aconteceu
submittedDefesa (ou esclarecimento) recebida; análise em andamento.
info_requestedA CorpX pediu esclarecimento. infoRequest.message e infoDueAt preenchidos.
decidedDecisão tomada. decision é accept ou refuse; decisionMessage explica.
balance_lockedValor retido na conta.
account_blockedConta bloqueada para a devolução.
balance_unlockedValor retido liberado.
refund_sentDevolução enviada; refund.amount e, quando houver, refund.endToEndId.
refund_completedDevolução liquidada. refundedTotal e remaining atualizados.
refund_failedA devolução não concluiu; a CorpX tenta de novo.
remainder_lockedO que faltou devolver ficou retido.
account_unblockedConta liberada.
closedDisputa encerrada (refunded ou refused).

Consultando disputas

GET /v1/accounts/{accountId}/pix/med?limit=50&offset=0

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.

{
"accountId": "773107de-...",
"tenantId": "tenant-suaempresa",
"items": [
{
"medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
"accountId": "773107de-...",
"tenantId": "tenant-suaempresa",
"endToEndId": "E303062942026021812490000005QLMv",
"transactionId": "tx-8f2c...",
"amount": 1000.00,
"reasonCode": "unauthorized-transaction",
"claimMessage": "Não reconheço esta transação",
"claimantBank": "Banco do reclamante",
"openedAt": "2026-02-18T19:34:14Z",
"clientAnswerDeadline": "2026-02-20T19:34:14Z",
"answered": false,
"reviewStatus": "awaiting_defense",
"infoDueAt": null,
"lockStatus": "locked",
"lockedAmount": 1000.00,
"refundedTotal": 0,
"remaining": 1000.00,
"refundPartial": false,
"updatedAt": "2026-02-18T19:34:16Z"
}
],
"count": 1,
"limit": 50,
"offset": 0
}

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

GET /v1/accounts/{accountId}/pix/med/{medId}

Tudo da listagem mais a linha do tempo, as mensagens trocadas, os anexos com downloadUrl e o que está habilitado agora:

{
"medId": "204cc938-...",
"reviewStatus": "info_requested",
"infoRequest": {
"message": "Envie o comprovante de entrega com o rastreio.",
"requestedAt": "2026-02-20T14:02:31Z",
"dueAt": "2026-02-21T14:02:31Z"
},
"canUpload": true,
"canAnswer": false,
"canMessage": true,
"canSubmit": true,
"events": [
{ "at": "2026-02-18T19:34:14Z", "kind": "opened", "reviewStatus": "awaiting_defense", "message": "Disputa aberta", "round": null, "step": null },
{ "at": "2026-02-19T14:02:31Z", "kind": "submitted", "reviewStatus": "pending_review", "message": "Defesa enviada", "round": null, "step": null },
{ "at": "2026-02-20T14:02:31Z", "kind": "info_requested", "reviewStatus": "info_requested", "message": "Esclarecimento solicitado", "round": null, "step": null }
],
"messages": [
{ "messageId": "medmsg_01...", "authorKind": "staff", "body": "Envie o comprovante de entrega com o rastreio.", "createdAt": "2026-02-20T14:02:31Z", "evidenceIds": [] }
],
"evidences": [
{ "evidenceId": "medev_9f1c...", "filename": "comprovante-entrega.pdf", "contentType": "application/pdf", "sizeBytes": 184320, "uploadedAt": "2026-02-19T13:58:00Z", "messageId": null, "scanStatus": "APPROVED", "downloadUrl": "https://..." }
],
"steps": []
}

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

POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/upload-url
{
"filename": "comprovante-entrega.pdf",
"contentType": "application/pdf",
"sizeBytes": 184320
}
{
"medId": "204cc938-...",
"evidenceId": "medev_9f1c...",
"key": "med-evidences/tenant-suaempresa/204cc938-.../medev_9f1c...-comprovante-entrega.pdf",
"uploadUrl": "https://...",
"method": "PUT",
"contentType": "application/pdf",
"sizeBytes": 184320,
"expiresIn": 900
}

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

POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/add
{
"key": "med-evidences/tenant-suaempresa/204cc938-.../medev_9f1c...-comprovante-entrega.pdf",
"evidenceId": "medev_9f1c...",
"filename": "comprovante-entrega.pdf",
"contentType": "application/pdf",
"sizeBytes": 184320,
"messageId": "medmsg_02..."
}

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

LimiteValor
Tipos aceitosapplication/pdf, image/jpeg, image/png, image/webp, text/plain, text/csv
Tamanho por arquivo5 MB
Total por disputa6 MB
Arquivos por disputa10
HTTPerrorCodeQuando
413file_too_largeArquivo acima de 5 MB.
413payload_too_largeO conjunto da disputa passaria de 6 MB.
422unsupported_media_typecontentType fora da lista.
422too_many_filesDécimo primeiro arquivo na mesma disputa.
409med_not_writableDisputa fora de awaiting_defense / info_requested.

Listando o que está anexado

GET /v1/accounts/{accountId}/pix/med/{medId}/evidence/download

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

POST /v1/accounts/{accountId}/pix/med/{medId}/answer
{
"result": "DISAGREE",
"reason": "Venda legítima: cliente cadastrado há 14 meses, produto entregue e rastreio confirmado em 19/02."
}
CampoObrigatórioDescrição
resultsimAGREE reconhece a fraude; DISAGREE contesta o relato.
reasonem DISAGREEA defesa, em texto livre.

Resposta 202:

{
"medId": "204cc938-...",
"result": "DISAGREE",
"answered": true,
"answeredAt": "2026-02-19T14:02:31Z",
"reviewStatus": "pending_review",
"message": "defesa registrada; a disputa segue para análise"
}

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:

HTTPerrorCodeQuando
400invalid_payloadresult fora de AGREE/DISAGREE.
409conflictA disputa já foi respondida.
422invalid_payloadDISAGREE sem reason.
404med_not_foundA disputa não existe ou não é desta conta.

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.

POST /v1/accounts/{accountId}/pix/med/{medId}/messages
{ "body": "Segue o comprovante de entrega com rastreio BR123456789BR." }

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).

POST /v1/accounts/{accountId}/pix/med/{medId}/submit

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

HTTPerrorCodeQuando
404med_not_foundDisputa inexistente ou de outra conta.
409med_not_writableMensagem ou anexo fora de awaiting_defense / info_requested.
409med_opened_by_usMED aberta pela CorpX em nome do correntista (direction: opened): não há o que responder.
422med_info_missingsubmit sem mensagem nem anexo novo.
403account_blockedOperação financeira na conta enquanto a devolução executa.

Taxa de MED

GET /v1/backoffice/tenants/{tenantId}/med-stats?days=30&accountId={accountId}

Devolve os contadores de prazo e a série diária da taxa:

CampoDescrição
totalTotal de disputas registradas.
awaitingAnswerDisputas ainda sem resposta sua.
dueSoonSem resposta e com menos de 12 horas de prazo.
overdueSem resposta e com prazo vencido.
openAmountValor somado das disputas ainda não encerradas.
nextDeadlineO prazo mais apertado entre as pendentes (vazio se não há pendência).
stats[]Série diária: date, pixInCount, pixInAmount, medCount, medAmount, quantityRatePercent, amountRatePercent.

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.

TaxaSituação
< 0,4%Saudável
0,4% – 1,0%Atenção, monitorar
> 1,0%Elevada, ações podem ser necessárias

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 motivo scam-or-fraud do liquidante.