MED (devoluções especiais)
O MED (Mecanismo Especial de Devolução) é o processo do Pix para casos de suspeita de fraude ou falha operacional. Quando o banco do pagador abre uma infração sobre um Pix que você recebeu, o valor pode ficar bloqueado até a análise, e você pode enviar uma defesa.
Importante
Disponível sob liberação. Sem ela, os endpoints respondem 403 com "MED is not enabled for this company".
Listar infrações
GET /api/med_infractions devolve as 100 infrações mais recentes da sua empresa.
GET /api/med_infractions/{id} devolve uma infração.
{
"id": "5e1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
"end_to_end_id": "E0000000020261006170312345678901",
"protocol": "MED-2026-000123",
"amount": "149.9",
"status": "ABERTA",
"lifecycle_status": "pending",
"situation_type": "…",
"fraud_type": "…",
"held": true,
"charge_id": "0f6e2a3c-7c1d-4f43-9b2f-5e8d9a4b1c22",
"defense_text": null
}
| Campo | Descrição |
|---|---|
end_to_end_id |
Identificador do Pix contestado; relaciona com a cobrança (charge_id). |
held |
true enquanto o valor está bloqueado pela infração. |
lifecycle_status |
Situação normalizada (abaixo). Use este campo nas suas regras. |
answerable |
true enquanto ainda dá para contestar ou aceitar. |
defense_deadline |
Prazo de finalização informado pela Efí, quando houver. |
lifecycle_status |
Significado |
|---|---|
pending |
Infração aberta ou em análise de defesa. |
reversed |
Infração procedente: o valor é devolvido ao pagador. |
failed |
Infração improcedente: o valor fica com você. |
cancelled |
Infração cancelada. |
Enviar defesa
POST /api/med_infractions/{id}/defense
curl -X POST https://marx.locosrv.com/api/med_infractions/5e1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8/defense \
-H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"defesa": "Pedido #1001 entregue em 07/10 com assinatura do recebedor. Comprovante disponível."}'
defesa é obrigatório (texto com evidências objetivas). Sem analise, a marx envia rejeitado: você contesta a infração e pede para ficar com o valor. analise: "aceito" concorda com a devolução ao pagador. A infração passa para EM_DEFESA e você recebe um webhook event_type_med.
O mesmo formulário está no painel, em MED, para quem tem a função liberada ou já tem uma infração. A Efí não recebe anexos por esse caminho.
Cada usuário da empresa recebe um e-mail, no idioma da conta, quando a infração aparece, muda de status ou recebe uma resposta:
| Momento | Assunto |
|---|---|
| Aberta, ainda dá para responder | precisa da sua resposta |
| Resposta enviada (contestação ou aceite) | resposta registrada |
Procedente (reversed) |
o valor será devolvido |
Improcedente (failed) |
o valor fica com você |
| Cancelada | infração cancelada |
O e-mail leva ao painel (/manager#/med/{id}). Ele não substitui o webhook.
Webhooks
event_type_med é enviado quando uma infração é aberta, muda de status ou recebe a sua defesa. O payload é o objeto acima.