MED (devoluções)

Acompanhe pela API os pedidos de devolução abertos pelo banco de quem pagou e o valor bloqueado.

O MED (Mecanismo Especial de Devolução do Pix) é um pedido do banco de quem pagou para devolver um Pix recebido, por suspeita de fraude, golpe ou falha. Quando um pedido chega, o valor passa do saldo disponível para o bloqueado até a decisão. Pela API você acompanha e responde: a defesa (texto e provas) vai pela API ou pelo painel, até o prazo. As provas não voltam para baixar: ficam guardadas com a WyzeCash e só vão para o banco de quem pagou.

​

Listar, consultar e responder

Método	Rota	Permissão	O que faz
GET	/v1/meds?limit=&cursor=	/meds/list	pedidos, do mais novo para o mais antigo
GET	/v1/meds/{id}	/meds/get	um pedido (MED-)
POST	/v1/meds/{id}/respond	/meds/respond	responde com a defesa e até 5 provas

{
  "id": "MED-5Q2W8M4Z3F7K",
  "original": { "id": "BKY-7KQ2M9XP4RZT", "payerName": "Ana Souza", "institution": "Banco Exemplo" },
  "status": "open",
  "statusTitle": "Aberto",
  "amount": 15000,
  "blocked": 15000,
  "owed": 0,
  "fee": 0,
  "receivedFee": 100,
  "receivedFeeOwed": 0,
  "reason": "fraud",
  "reasonTitle": "Fraude",
  "description": "Pagador alega não reconhecer a compra.",
  "deadline": "2026-10-15T15:04:11.000Z",
  "defense": null,
  "attachments": [],
  "decisionNote": null,
  "defenseAt": null,
  "decidedAt": null,
  "createdAt": "2026-10-08T15:04:11.000Z"
}

Campo	O que é
original	o Pix recebido em disputa: a cobrança, quem pagou e o banco
status, statusTitle	open Aberto · analysis Em análise · refunded Devolvido · rejected Contestado (você ganhou)
amount	valor pedido
blocked	quanto está bloqueado agora (pode ser menor que amount se o saldo não cobria tudo)
owed	devolvido sem saldo suficiente: o que ainda falta e sai dos próximos recebimentos
fee	contestado: tarifa descontada ao liberar o bloqueio
receivedFee, receivedFeeOwed	taxa de MED recebido (cobrada quando o pedido chega) e quanto dela ainda falta
reason, reasonTitle	fraud Fraude · scam Golpe · operational Falha operacional
deadline	prazo para enviar a defesa
defense, attachments, defenseAt	a defesa enviada e as provas (só o nome, o tipo e o tamanho)
decisionNote, decidedAt	motivo e hora da decisão

​

O que muda no dinheiro

• Abriu: amount sai do disponível para o bloqueado, até onde houver saldo. Enquanto está aberto, todo dinheiro que entra primeiro completa o bloqueio.
• Contestado (você ganhou): o bloqueado volta ao disponível, menos a tarifa (fee).
• Devolvido: o valor sai de vez. Se ainda faltar, vira owed e os próximos recebimentos cobrem antes de ficar disponível. GET /v1/balance traz o total em medOwed.

Enquanto um pedido está aberto, a cobrança de origem não pode ser estornada (MED_IN_PROGRESS).