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.
Ciclo de vida
Situação (status) | Webhook | O que significa |
|---|---|---|
WAITING_PSP | med.opened | Contestação aberta e em análise. Se ela foi aberta há até 48 horas, o valor fica bloqueado no seu saldo enquanto é analisada. |
ACCEPTED | med.accepted | Aceita: o valor foi devolvido ao pagador e o desconto no seu saldo é mantido. |
REJECTED | med.rejected | Reprovada (recusada): encerrada a seu favor. O valor bloqueado volta pro seu saldo. |
CANCELLED | med.cancelled | Cancelada. O valor bloqueado volta pro seu saldo. |
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.
{
"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âmetro | Tipo | Descrição |
|---|---|---|
id | number | Identificador da contestação (o mesmo em todos os eventos dela) |
transactionId | string | null | ID da cobrança contestada, quando ela é encontrada na VamPay |
externalId | string | null | externalId da cobrança contestada |
externalReference | string | null | A referência do seu pedido, se você enviou na cobrança |
endToEndId | string | null | Identificador do PIX |
type | string | Tipo informado pela instituição (o texto varia; o valor do exemplo é ilustrativo) |
status | string | WAITING_PSP, ACCEPTED, REJECTED ou CANCELLED |
amount | number | Valor contestado, em reais |
reason | string | null | Motivo informado na contestação |
analysisResult / analysisDetails | string | null | Resultado e detalhes da análise, quando houver |
balanceHeld | boolean | true no med.opened quando o valor ficou bloqueado no seu saldo |
openedAt / updatedAt | string | Datas ISO 8601 |
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
/medsLista as contestações das suas cobranças, da mais recente pra mais antiga.
| Parâmetro | Tipo | Descrição |
|---|---|---|
page | number | Página (padrão: 1) |
limit | number | Itens por página, de 5 a 50 (padrão: 10) |
status | string | ALL (padrão), WAITING_PSP, ACCEPTED, REJECTED ou CANCELLED |
search | string | Busca por texto (até 100 caracteres) |
curl -X GET "https://api.vampay.com.br/meds?status=WAITING_PSP&limit=10" \
-H "X-API-Key: vampay_sua_api_key"{
"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 }
}/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.
/meds/availabilityDiz se você tem contestação em análise agora.
{ "success": true, "data": { "active": true, "pending": 1, "awaitingAdmin": 0 } }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.