VamPay
VamPay

MED (contestações)

Como acompanhar uma contestação de PIX por suspeita de fraude: situações, webhooks e consulta pela API.

O que é

O MED (Mecanismo Especial de Devolução do PIX) é o processo em que um pagador ou o banco dele contesta um PIX por suspeita de fraude ou golpe. A equipe da VamPay cuida da defesa direto com a instituição: você não precisa responder nada. O que você faz é acompanhar, e a VamPay avisa você a cada mudança.

Cada integrador recebe só as contestações das suas próprias cobranças. Os avisos chegam pelo sino e pelas notificações do painel e, se você tem webhook configurado, também por webhook (veja abaixo).

Ciclo de vida

Situação (status)Webhook
WAITING_PSPmed.opened
ACCEPTEDmed.accepted
REJECTEDmed.rejected
CANCELLEDmed.cancelled

Webhooks de MED

Os eventos de MED usam os mesmos destinos, a mesma assinatura (X-vp-Signature) e as mesmas tentativas dos webhooks de transação. Um evento sai por mudança: ao abrir e ao encerrar. Contestações antigas, que você só vê depois de já encerradas, não geram evento.

med.openedjson
{
  "event": "med.opened",
  "data": {
    "id": 4821,
    "transactionId": "507f1f77bcf86cd799439011",
    "externalId": "txn_abc123",
    "externalReference": "pedido-123",
    "endToEndId": "E12345678202610291200abcdef12345",
    "type": "FRAUD",
    "status": "WAITING_PSP",
    "amount": 99.90,
    "currency": "BRL",
    "reason": "Pagamento não reconhecido pelo titular",
    "analysisResult": null,
    "analysisDetails": null,
    "balanceHeld": true,
    "openedAt": "2026-10-29T14:00:00.000Z",
    "updatedAt": "2026-10-29T14:00:00.000Z"
  },
  "timestamp": "2026-10-29T14:00:02.000Z"
}
ParâmetroTipo
idnumber
transactionIdstring | null
externalIdstring | null
externalReferencestring | null
endToEndIdstring | null
typestring
statusstring
amountnumber
reasonstring | null
analysisResult / analysisDetailsstring | null
balanceHeldboolean
openedAt / updatedAtstring
Os eventos do MED são med.opened, med.accepted, med.rejected e med.cancelled. Para saber se uma contestação já foi encerrada, considere qualquer um dos três últimos.

Consultar pela API

GET/meds

Lista as contestações das suas cobranças, da mais recente pra mais antiga.

ParâmetroTipo
pagenumber
limitnumber
statusstring
searchstring
curlbash
curl -X GET "https://api.vampay.com.br/meds?status=WAITING_PSP&limit=10" \
  -H "X-API-Key: vampay_sua_api_key"
200 OKjson
{
  "success": true,
  "data": [
    {
      "_id": "6720a1b2c3d4e5f6a7b8c9d0",
      "providerId": 4821,
      "transactionId": "507f1f77bcf86cd799439011",
      "type": "FRAUD",
      "status": "WAITING_PSP",
      "endToEndId": "E12345678202610291200abcdef12345",
      "reportDetails": "Pagamento não reconhecido pelo titular",
      "amount": 99.9,
      "currency": "BRL",
      "createdAt": "2026-10-29T14:00:02.000Z"
    }
  ],
  "summary": {
    "total": 3,
    "pending": 1,
    "pendingAmount": 99.9,
    "accepted": 1,
    "rejected": 1,
    "cancelled": 0
  },
  "pagination": { "page": 1, "limit": 10, "total": 1, "pages": 1 }
}
GET/meds/{id}

Detalhes de uma contestação. O id é o campo _id da listagem. Responde 404 se ela não for das suas cobranças.

GET/meds/availability

Diz se você tem contestação em análise agora.

200 OKjson
{ "success": true, "data": { "active": true, "pending": 1, "awaitingAdmin": 0 } }
O envio de defesa pela API não existe: POST /meds/{id}/defense responde 403 com a mensagem “As mediações são tratadas pela nossa equipe. Você não precisa responder.” A defesa é sempre feita pela VamPay.