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. |
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.loco.ltd/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 da sua defesa, com evidências objetivas). A infração passa para EM_DEFESA e você recebe um webhook event_type_med.
Webhooks
event_type_med é enviado quando uma infração é aberta, muda de status ou recebe a sua defesa. O payload é o objeto acima.