Quando um pagador abre uma contestação, a Plowf notifica você imediatamente via webhook com o evento MED. É por ali que você fica sabendo que precisa agir — e o objeto do evento contém tudo que você precisa para analisar e responder.
Para mais detalhes sobre o evento MED e a descrição completa de todos os campos do payload, consulte a referência do evento MED. Estrutura do webhook
O evento MED é enviado a cada mudança de status. Implemente idempotência no seu endpoint usando o uuid do MED para evitar processar o mesmo evento mais de uma vez.
{
"event": "MED",
"timestamp": "2024-01-15T12:00:00Z",
"data": {
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"med_type": "RECEIVED_MED",
"dispute_type": "SCAM",
"status": "PENDING",
"resolved": false,
"pix_in_transaction": {
"value": "150.00",
"end_to_end": "E00000000202401011000abcdef12345",
"settled_at": "2024-01-01T10:05:00Z"
}
}
}
Campos do objeto MED
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"med_type": "RECEIVED_MED",
"dispute_type": "SCAM",
"status": "PENDING",
"resolved": false,
"pix_in_transaction": {
"value": "150.00",
"end_to_end": "E00000000202401011000abcdef12345",
"settled_at": "2024-01-01T10:05:00Z"
}
}
| Campo | Tipo | Descrição |
|---|
uuid | string | Identificador único do MED — use para idempotência e para enviar a resposta |
med_type | enum | Direção da contestação em relação à sua conta |
dispute_type | enum | Motivo alegado pelo contestante |
status | enum | Fase atual do MED no ciclo de vida |
resolved | boolean | true quando o MED chegou ao status final (ACCEPTED, REJECTED ou CANCELLED) |
pix_in_transaction | object | Dados do PIX contestado |
pix_in_transaction.value | string | Valor em reais do PIX contestado |
pix_in_transaction.end_to_end | string | ID fim a fim do PIX — use para localizar a transação no seu sistema |
pix_in_transaction.settled_at | string | Data e hora em que o PIX foi liquidado |
med_type — direção da contestação
| Valor | Significado |
|---|
RECEIVED_MED | Você recebeu uma contestação — alguém quer de volta um PIX que te enviou |
REQUESTED_MED | Você abriu uma contestação de um PIX que enviou |
RECEIVED_MED: um cliente contestou um pagamento e você precisa aceitar ou rejeitar a devolução.
dispute_type — motivo da contestação
| Valor | Descrição | O que costuma indicar |
|---|
SCAM | Fraude ou golpe | O pagador alega ter sido enganado para realizar o pagamento |
WRONG_TRANSACTION | Transação enviada por engano | O pagador enviou para a chave errada ou pelo valor errado |
COERCION_CRIME | Crime de coação | O pagamento foi feito sob ameaça (ex: sequestro relâmpago) |
UNAUTHORIZED_ACCESS | Acesso não autorizado | A conta do pagador foi invadida e o PIX foi feito sem seu consentimento |
UNDEFINED | Motivo não definido | Contestação sem motivo especificado |
dispute_type para calibrar sua análise. WRONG_TRANSACTION costuma ser mais fácil de refutar com evidências de entrega. COERCION_CRIME e UNAUTHORIZED_ACCESS tendem a ter maior peso regulatório.
status — ciclo de vida
PENDING → PROCESSING → ACCEPTED
→ REJECTED
→ CANCELLED
| Status | resolved | O que fazer |
|---|
PENDING | false | Aja agora: você precisa responder dentro do prazo |
PROCESSING | false | Aguarde — o MED está em processo de resposta |
ACCEPTED | true | MED aceito — valor devolvido ao pagador |
REJECTED | true | MED rejeitado — valor permanece na sua conta |
CANCELLED | true | MED cancelado — nenhuma ação necessária |
MEDs com status: "PENDING" têm prazo de resposta regulado pelo Banco Central. Se não responder a tempo, o MED pode ser aceito automaticamente e o valor devolvido.
Como decidir o que fazer
Ao receber um RECEIVED_MED com status: "PENDING", avalie:
Rejeite o MED se você tem evidências de que a transação foi legítima:
- Nota fiscal ou recibo do produto/serviço
- Comprovante de entrega
- Registro de uso do serviço (log de acesso, ativação de licença, etc.)
- Histórico de comunicação com o cliente
Aceite o MED se:
- A contestação faz sentido e você reconhece o erro
- Você não tem evidências suficientes para contestar
- O valor ou o esforço não justificam a disputa
Para o passo a passo de como enviar a resposta via API, consulte a receita Responder a um MED. 
