Disputas (MED)
Conteste disputas PIX (MED) pela API: liste, envie defesa (upload ou link) e receba webhooks com o resultado.
Disputas (MED)
A MED (Mecanismo Especial de Devolução) é a disputa/contestação do PIX prevista pelo Banco Central. Quando um pagador abre uma MED sobre uma transação, o valor correspondente é bloqueado no seu saldo e você tem 48 horas para enviar a sua defesa. A Zypfy encaminha a defesa à adquirente e, ao final, libera o valor (defesa aceita) ou debita em definitivo (defesa recusada).
Esta API permite listar suas MEDs, ver detalhes, enviar a defesa e receber notificações por webhook — sem precisar acessar o painel.
Fluxo completo
1. Pagador abre a disputa ──▶ Zypfy bloqueia o valor e cria a MED
│
▼
2. Zypfy notifica ──▶ webhook med.created (prazo de 48h começa)
│
3. Você envia a defesa ──▶ POST /api/meds/{id}/defense
│
▼
webhook med.defense_received
│
4. Análise da adquirente / decisão final
│
▼
webhook med.resolved { result: "won" | "lost" }
won -> defesa aceita: valor liberado
lost -> defesa recusada: valor debitadoStatus
| Status | Significado |
|---|---|
AWAITING_DEFENSE | Aguardando sua defesa (dentro do prazo de 48h). |
DEFENSE_SUBMITTED | Defesa enviada; em análise. |
ACCEPTED | A MED procedeu — valor debitado do seu saldo. |
REJECTED | Defesa aceita — valor liberado de volta. |
CANCELED | Disputa cancelada. |
Listar MEDs
GET https://api.zypfy.com/api/medsParâmetros de query (opcionais): page, per_page (máx 100), status, search (busca por end-to-end ou dispute id).
curl https://api.zypfy.com/api/meds?status=AWAITING_DEFENSE \
-H "Authorization: Bearer SEU_TOKEN"{
"page": 1,
"per_page": 20,
"total": 1,
"total_pages": 1,
"data": [
{
"id": 101,
"end_to_end_id": "E1820855202606141200abcdef0001",
"dispute_id": "9a8d4e19-71a7-4a1f-ae03-f660d5a5f676",
"status": "AWAITING_DEFENSE",
"dispute_reason": "Pagamento nao reconhecido pelo cliente",
"amount": 150.5,
"amount_blocked": 150.5,
"owner_source": "deposit",
"transaction_id": 663502,
"deadline_at": "2026-06-16T12:00:00.000Z",
"can_defend": true
}
]
}Detalhe de uma MED
GET https://api.zypfy.com/api/meds/{id}Retorna os dados da disputa, a transação de origem e os documentos já anexados. Documentos enviados por link trazem a url; documentos enviados por upload ficam internos (não retornam URL).
Enviar a defesa
POST https://api.zypfy.com/api/meds/{id}/defenseSó é possível enquanto a MED estiver em AWAITING_DEFENSE e dentro do prazo de 48h. Envie um texto de defesa e, opcionalmente, até 5 documentos — por upload de arquivo, por link, ou os dois juntos.
Campos:
| Campo | Obrigatório | Descrição |
|---|---|---|
defense_text | Sim | Texto da defesa (mínimo 10 caracteres). |
documents | Não | Arquivos (PDF, JPG ou PNG). Máx 5 documentos no total. |
document_urls | Não | Lista de { "url", "description" } com links HTTPS públicos. Máx 5 documentos no total. |
Opção A — apenas links (JSON)
curl -X POST https://api.zypfy.com/api/meds/101/defense \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"defense_text": "Transacao legitima. Segue comprovante de entrega e conversa com o cliente.",
"document_urls": [
{ "url": "https://seudominio.com/comprovantes/nota.pdf", "description": "Nota fiscal" },
{ "url": "https://seudominio.com/comprovantes/entrega.png", "description": "Comprovante de entrega" }
]
}'Opção B — upload de arquivos (multipart)
curl -X POST https://api.zypfy.com/api/meds/101/defense \
-H "Authorization: Bearer SEU_TOKEN" \
-F "defense_text=Transacao legitima, segue documentacao." \
-F "[email protected];type=application/pdf" \
-F 'document_urls=[{"url":"https://seudominio.com/extra.pdf","description":"Anexo extra"}]'{ "message": "Defesa enviada com sucesso.", "documents_count": 2 }Webhooks
Configure uma URL dedicada para eventos de MED no seu painel (campo webhook_url_med). Se não houver uma URL específica de MED, usamos a sua URL de webhook geral. Quando configurada, a assinatura vai no header X-Webhook-Signature.
Eventos enviados (POST com corpo JSON):
| Evento | Quando |
|---|---|
med.created | Uma nova MED foi aberta (começa o prazo de 48h). |
med.defense_received | Recebemos a sua defesa. |
med.resolved | Decisão final (result: won ou lost). |
{
"type": "Med",
"event": "med.resolved",
"med_id": 101,
"end_to_end_id": "E1820855202606141200abcdef0001",
"dispute_id": "9a8d4e19-71a7-4a1f-ae03-f660d5a5f676",
"status": "REJECTED",
"amount": 150.5,
"amount_blocked": 150.5,
"deadline_at": "2026-06-16T12:00:00.000Z",
"result": "won"
}