Infrações e MED

Quando o pagador contesta um Pix que você recebeu (Mecanismo Especial de Devolução, MED), o liquidante abre uma infração sobre a transação. A MonkeyPay avisa pelo webhook, bloqueia o valor contestado na carteira e aceita a sua defesa pela API.

1. Receba o aviso

Cadastre a URL infraction na configuração de webhooks (veja o guia Webhooks). Cada abertura ou mudança de estado da infração gera um POST com o corpo da transação e o objeto infraction:

• O corpo não traz o nome do evento. Se a URL infraction for a mesma dos outros estados, identifique a infração pela presença do objeto infraction.
• status no nível raiz é o estado da transação; o da infração está em infraction.status.
• Guarde infraction.id: ele é usado na consulta e na defesa.
• reportedBy, analysisResult e analysisDetails repetem o que o liquidante informou e podem vir null.

2. Entenda o bloqueio

Ao abrir a infração, infraction.amount fica bloqueado no saldo da carteira. Esse valor pode ser menor que o da transação (contestação parcial). O desfecho decide o que acontece com ele:

Estados intermediários (waiting_psp, open, acknowledged, analysing, defended, answered, waiting_adjustments) mantêm o bloqueio.

Se a infração chegar a closed e o valor seguir bloqueado, fale com o suporte informando o infraction.id.

Tipos (infraction.type): refund_request (pedido de devolução), fraud (suspeita de fraude) e refund_cancelled (pedido de devolução cancelado).

3. Consulte a infração

GET /resource/infractions lista as infrações da organização do token e das suborganizações vinculadas, com paginação. A empresa-mãe pode consultar os casos das suas subempresas; a credencial de uma subempresa não alcança os casos da mãe ou de uma empresa irmã. Use organizationId para filtrar uma organização dentro do seu alcance.

Devolve a infração com transactionId, externalId, walletId, accountId, status, type, amount, reason, createdAt e updatedAt. account traz id, bankCode, bankIspb, bankName, agency, accountNumber, holder, type e status, ou vem null; pixTransaction traz só endToEnd, ou vem null. O detalhe não devolve o documento do titular da conta nem os dados de pagador e recebedor do Pix. Infração fora do alcance da credencial responde 404.

4. Envie a defesa

A defesa é enviada uma única vez por infração, em multipart/form-data:

A resposta 201 confirma o registro da defesa e traz a mediação em data, com id, status (pending) e os links temporários dos anexos. Ela não confirma recebimento ou decisão do liquidante.

Consulte o estado registrado por GET /resource/mediations/{mediationId}. GET /resource/mediations lista as mediações da organização do token e das suborganizações vinculadas. Mudanças em infraction.status também podem chegar pelo webhook, mas não devem ser interpretadas como confirmação de envio ou decisão sobre a defesa. Uma atualização da mediação depende do processamento das informações do liquidante.

Permissões

A consulta da infração exige o escopo monkeypay:infractions:read; enviar a defesa exige monkeypay:mediations:write, e acompanhá-la, monkeypay:mediations:read. Resposta 403 indica que a sua credencial não tem esses escopos: peça a habilitação ao suporte.