Infracciones PIX y MED

Esta pagina explica como acompanar y responder disputas PIX relacionadas al MED por la API Minha Konta.

Resumen

Una infraccion PIX es una disputa abierta por la institucion del pagador. Cuando requiere analisis, recibes webhooks, puedes consultar el MED y puedes enviar una defensa con contexto y evidencias dentro del plazo informado.

1. Conceptos Principales

Concepto	Descripcion
Infraccion PIX	Disputa formal relacionada a un PIX recibido
MED	Flujo regulatorio usado para analisis y eventual devolucion
Bloqueo cautelar	Reserva temporal del valor disputado mientras el caso es analizado
Defensa	Justificativa enviada por el cliente, con evidencias cuando existan
Decision	Resultado final del caso, con devolucion o liberacion del valor

El MED es parte del ciclo regulatorio de disputas. Puede impactar el saldo disponible mientras el caso esta en analisis.

2. Como Acompanhar

Usa webhooks para recibir actualizaciones en tiempo real:

Evento	Cuando usar
`pix.infraction.created`	Una disputa fue registrada y requiere seguimiento
`pix.refund.requested`	Un valor entro en disputa MED
`pix.infraction.defense_submitted`	Una defensa fue registrada
`pix.infraction.resolved`	La disputa fue finalizada
`pix.refund.completed`	La devolucion fue ejecutada
`pix.payout.returned`	El lanzamiento de devolucion fue confirmado

Consulta ejemplos en Payloads de Webhook.

3. Consulta via API

http

GET /api/external/med
GET /api/external/med/{id}

Permiso requerido: payment:read.

Usa el id retornado por webhooks o por la lista para consultar el caso y correlacionarlo con el original_end_to_end_id del PIX disputado.

4. Enviar Defensa via API

http

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

Permiso requerido: payment:write.

El body debe ser JSON y firmado con el mismo patron HMAC usado en los demas endpoints POST de la API externa.

json

{
  "defense_text": "Cliente confirmo la operacion y envio evidencia del atendimento.",
  "evidence": [
    {
      "type": "whatsapp",
      "url": "https://su-dominio.example/evidencias/med-123.png",
      "description": "Captura de conversacion con confirmacion del titular",
      "source": "whatsapp",
      "filename": "conversacion-med-123.png",
      "received_at": "2026-06-02T13:30:00Z"
    }
  ]
}

Campo	Tipo	Obligatorio	Descripcion
`defense_text`	string	Si	Texto de la defensa y contexto de la disputa
`evidence`	array	No	Lista de evidencias referenciadas por URL o descripcion
`evidence[].type`	string	No	`url`, `document`, `image`, `screenshot`, `email`, `whatsapp` u `other`
`evidence[].url`	string	Condicional	URL `https` o `http` de evidencia hospedada por el cliente
`evidence[].description`	string	Condicional	Resumen de la evidencia cuando no haya URL

Cada item de evidence debe contener al menos url o description. La API acepta hasta 10 evidencias por envio.

Evidencias

La API externa registra texto y referencias de evidencia. Upload binario de anexos esta disponible en los portales Minha Konta, donde los archivos son validados y almacenados para analisis y auditoria.

5. Portales y Evidencias Externas

Las defensas tambien pueden ser tratadas en los portales Minha Konta. Ese camino permite anexar archivos directamente, como PDFs, imagenes, capturas, contratos e historiales de atencion.

Cuando evidencias llegan por e-mail, WhatsApp, soporte u otro canal fuera de la API, la operacion Minha Konta puede registrarlas en el caso. Las evidencias quedan archivadas para consulta, revision futura y auditoria.

6. Plazos

El plazo de respuesta viene en defense_deadline en los webhooks relacionados a la infraccion. Responde antes de ese plazo para que la defensa pueda ser analizada y enviada correctamente.

Recomendaciones:

Monitorea pix.infraction.created y pix.refund.requested.
Consulta el MED por el id recibido.
Envia la defensa por API o portal tan pronto tengas la informacion del cliente.
Guarda e2e_id, med_id y horario de envio.

7. Reconciliacion

Usa e2e_id como llave de correlacion entre el PIX original, webhooks de infraccion, registro MED y eventual devolucion.

`analysis_result`	Interpretacion
`AGREED`	Disputa aceptada y devolucion ejecutada
`DISAGREED`	Defensa aceptada o disputa rechazada, sin devolucion
`null`	Caso cancelado o sin decision aplicable

Infracciones PIX y MED ​

1. Conceptos Principales ​

2. Como Acompanhar ​

3. Consulta via API ​

4. Enviar Defensa via API ​

5. Portales y Evidencias Externas ​

6. Plazos ​

7. Reconciliacion ​