ZypfyDocs Acessar painel
Guia de integração

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

código
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 debitado

Status

StatusSignificado
AWAITING_DEFENSEAguardando sua defesa (dentro do prazo de 48h).
DEFENSE_SUBMITTEDDefesa enviada; em análise.
ACCEPTEDA MED procedeu — valor debitado do seu saldo.
REJECTEDDefesa aceita — valor liberado de volta.
CANCELEDDisputa cancelada.

Listar MEDs

código
GET https://api.zypfy.com/api/meds

Parâmetros de query (opcionais): page, per_page (máx 100), status, search (busca por end-to-end ou dispute id).

bash
curl https://api.zypfy.com/api/meds?status=AWAITING_DEFENSE \
  -H "Authorization: Bearer SEU_TOKEN"
json
{
  "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

código
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

código
POST https://api.zypfy.com/api/meds/{id}/defense

Só é 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:

CampoObrigatórioDescrição
defense_textSimTexto da defesa (mínimo 10 caracteres).
documentsNãoArquivos (PDF, JPG ou PNG). Máx 5 documentos no total.
document_urlsNãoLista de { "url", "description" } com links HTTPS públicos. Máx 5 documentos no total.
bash
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)

bash
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"}]'
json
{ "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):

EventoQuando
med.createdUma nova MED foi aberta (começa o prazo de 48h).
med.defense_receivedRecebemos a sua defesa.
med.resolvedDecisão final (result: won ou lost).
json
{
  "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"
}