Infrações PIX e MED

Esta página descreve como acompanhar e responder contestações PIX relacionadas ao MED (Mecanismo Especial de Devolução) pela API Minha Konta.

Resumo

Uma infração PIX é uma contestação aberta pela instituição do pagador. Quando ela exige análise, você recebe webhooks, pode consultar o MED e pode enviar uma defesa com justificativa e evidências dentro do prazo informado.

---

1. Conceitos principais

Conceito	Descrição
Infração PIX	Contestação formal relacionada a um PIX recebido
MED	Fluxo regulatório usado para análise e eventual devolução de valores
Bloqueio cautelar	Reserva temporária do valor em disputa enquanto o caso é analisado
Defesa	Justificativa enviada pelo cliente, acompanhada de evidências quando houver
Decisão	Resultado final do caso, com devolução ou liberação do valor

O MED é uma camada regulatória do ciclo de contestação. Ele pode impactar o saldo disponível enquanto o caso está em análise.

---

2. Como acompanhar

Use webhooks para receber atualizações em tempo real:

Evento	Quando usar
pix.infraction.created	Uma contestação foi registrada e requer acompanhamento
pix.refund.requested	Um valor entrou em disputa no fluxo MED
pix.infraction.defense_submitted	Uma defesa foi registrada
pix.infraction.resolved	A contestação foi finalizada
pix.refund.completed	A devolução foi executada
pix.payout.returned	O lançamento de devolução foi confirmado

Veja os payloads em Payloads de Webhook.

---

3. Consulta via API

Listar MEDs

GET /api/external/med

Permissão exigida: payment:read.

Consultar um MED

GET /api/external/med/{id}

Permissão exigida: payment:read.

Use o id retornado nos webhooks ou na listagem para consultar o caso e correlacionar com o original_end_to_end_id do PIX contestado.

---

4. Enviar defesa pela API

POST /api/external/med/{id}/defense
Content-Type: application/json
Authorization: ApiKey {client_id}:{client_secret}
hmac: {assinatura_hmac_sha512}

Permissão exigida: payment:write.

Este endpoint registra a defesa do MED para análise. O corpo deve ser JSON e assinado pelo mesmo padrão HMAC usado nos demais endpoints POST da API externa.

Body

{
  "defense_text": "Cliente confirmou a operação e enviou comprovante do atendimento.",
  "evidence": [
    {
      "type": "whatsapp",
      "url": "https://seu-dominio.example/evidencias/med-123.png",
      "description": "Print da conversa com confirmação do titular",
      "source": "whatsapp",
      "filename": "conversa-med-123.png",
      "received_at": "2026-06-02T13:30:00Z"
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
defense_text	string	Sim	Texto da defesa e contexto da contestação
evidence	array	Não	Lista de evidências referenciadas por URL ou descrição
evidence[].type	string	Não	url, document, image, screenshot, email, whatsapp ou other
evidence[].url	string	Condicional	URL https ou http para evidência hospedada pelo cliente
evidence[].description	string	Condicional	Resumo da evidência quando não houver URL
evidence[].source	string	Não	Origem da evidência, como email, whatsapp, support ou external_api
evidence[].filename	string	Não	Nome de referência do arquivo
evidence[].received_at	string	Não	Data/hora em que a evidência foi recebida

Cada item de evidence deve conter ao menos url ou description. A API aceita até 10 evidências por submissão.

Evidências

A API externa registra texto e referências de evidência. Upload binário de anexos é feito pelos portais Minha Konta, onde os arquivos são validados e armazenados para análise e auditoria.

Resposta

{
  "worked": true,
  "status": "defense_submitted",
  "med_id": "3f1e2c41-c269-4fa8-a151-49e739f8d37d",
  "block_id": "3f1e2c41-c269-4fa8-a151-49e739f8d37d",
  "evidence_count": 1,
  "defense_submitted_at": "2026-06-02T16:30:12Z"
}

Erros comuns

Status	Motivo
400	defense_text ausente, JSON inválido, evidência inválida ou URL fora do padrão aceito
401	API Key ou HMAC ausente/inválido
403	IP fora da whitelist ou API Key sem payment:write
404	MED não encontrado para a conta da API Key
409	MED não está mais em estado que permite defesa

---

5. Portais e evidências externas

As mesmas defesas também podem ser tratadas nos portais Minha Konta. Esse caminho permite anexar arquivos diretamente, como PDFs, imagens, prints, contratos e históricos de atendimento.

Quando evidências chegam por e-mail, WhatsApp, atendimento ou outro canal fora da API, elas podem ser registradas no caso pela operação Minha Konta. As evidências ficam arquivadas para consulta, conferência futura e auditoria.

Envio ao fluxo regulatório

O texto da defesa e o parecer final são usados na resposta do caso. Arquivos anexados e demais evidências permanecem armazenados na Minha Konta para análise e histórico.

---

6. Prazos

O prazo de resposta vem no campo defense_deadline dos webhooks relacionados à infração. Responda antes desse prazo para que a defesa possa ser analisada e encaminhada corretamente.

Recomendações:

• Monitore pix.infraction.created e pix.refund.requested.
• Consulte o MED pelo id recebido.
• Envie a defesa pela API ou pelo portal assim que tiver os dados do cliente.
• Guarde no seu sistema o e2e_id, o med_id e o horário da submissão.

---

7. Reconciliação

Use o e2e_id como chave de correlação entre:

• PIX original recebido.
• Webhooks de infração.
• Registro MED consultado pela API.
• Eventual devolução confirmada por pix.refund.completed ou pix.payout.returned.

Quando pix.infraction.resolved chegar, use analysis_result para atualizar o status interno do caso.

analysis_result	Interpretação
AGREED	Contestação aceita e devolução executada
DISAGREED	Defesa aceita ou contestação rejeitada, sem devolução
null	Caso cancelado ou sem decisão aplicável