PIX Infractions and MED

This page explains how to track and respond to PIX disputes related to MED (Special Refund Mechanism) through the Minha Konta API.

Summary

A PIX infraction is a dispute opened by the payer's institution. When it requires analysis, you receive webhooks, can query the MED case, and can submit a defense with context and evidence within the informed deadline.

---

1. Main Concepts

Concept	Description
PIX infraction	Formal dispute related to a PIX you received
MED	Regulatory flow for analysis and possible refund
Preventive block	Temporary reservation of the disputed amount while the case is analyzed
Defense	Explanation submitted by the customer, with evidence when available
Decision	Final case result, with refund or release of the disputed amount

MED is part of the regulatory dispute cycle. It may affect the available balance while the case is under analysis.

---

2. How to Track

Use webhooks to receive real-time updates:

Event	When to use
pix.infraction.created	A dispute was registered and requires tracking
pix.refund.requested	An amount entered the MED dispute flow
pix.infraction.defense_submitted	A defense was registered
pix.infraction.resolved	The dispute was finalized
pix.refund.completed	The refund was executed
pix.payout.returned	The refund entry was confirmed

See payload examples in Webhook Payloads.

---

3. Query Through API

List MEDs

GET /api/external/med

Required permission: payment:read.

Get a MED

GET /api/external/med/{id}

Required permission: payment:read.

Use the id returned by webhooks or by the list endpoint to query the case and correlate it with the disputed PIX original_end_to_end_id.

---

4. Submit Defense Through API

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

Required permission: payment:write.

This endpoint registers the MED defense for analysis. The body must be JSON and signed with the same HMAC pattern used by other POST endpoints in the External API.

Body

{
  "defense_text": "Customer confirmed the operation and sent service evidence.",
  "evidence": [
    {
      "type": "whatsapp",
      "url": "https://your-domain.example/evidence/med-123.png",
      "description": "Conversation screenshot confirming the holder's request",
      "source": "whatsapp",
      "filename": "conversation-med-123.png",
      "received_at": "2026-06-02T13:30:00Z"
    }
  ]
}

Field	Type	Required	Description
defense_text	string	Yes	Defense text and dispute context
evidence	array	No	List of evidence references by URL or description
evidence[].type	string	No	url, document, image, screenshot, email, whatsapp, or other
evidence[].url	string	Conditional	https or http URL for customer-hosted evidence
evidence[].description	string	Conditional	Evidence summary when no URL is available
evidence[].source	string	No	Evidence source, such as email, whatsapp, support, or external_api
evidence[].filename	string	No	Reference filename
evidence[].received_at	string	No	Time when the evidence was received

Each evidence item must include at least url or description. The API accepts up to 10 evidence references per submission.

Evidence

The External API stores text and evidence references. Binary file uploads are available in the Minha Konta portals, where files are validated and stored for analysis and audit.

Response

{
  "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"
}

Common Errors

Status	Reason
400	Missing defense_text, invalid JSON, invalid evidence, or invalid URL
401	Missing or invalid API Key or HMAC
403	IP outside whitelist or API Key without payment:write
404	MED not found for the API Key account
409	MED no longer accepts defense

---

5. Portals and External Evidence

The same defenses can also be handled in the Minha Konta portals. This path allows direct file attachments, such as PDFs, images, screenshots, contracts, and support history.

When evidence arrives by email, WhatsApp, support, or any other channel outside the API, the Minha Konta operation can register it in the case. Evidence remains archived for consultation, future review, and audit.

Regulatory Submission

The defense text and final analyst opinion are used in the case response. Attachments and other evidence remain stored at Minha Konta for analysis and history.

---

6. Deadlines

The response deadline is sent in the defense_deadline field of infraction-related webhooks. Respond before this deadline so the defense can be reviewed and forwarded correctly.

Recommendations:

• Monitor pix.infraction.created and pix.refund.requested.
• Query the MED case by the received id.
• Submit the defense through the API or portal as soon as you have the customer's information.
• Store the e2e_id, med_id, and submission time in your system.

---

7. Reconciliation

Use e2e_id as the correlation key between:

• Original PIX received.
• Infraction webhooks.
• MED record queried through the API.
• Possible refund confirmed by pix.refund.completed or pix.payout.returned.

When pix.infraction.resolved arrives, use analysis_result to update your internal case status.

analysis_result	Interpretation
AGREED	Dispute accepted and refund executed
DISAGREED	Defense accepted or dispute rejected, with no refund
null	Cancelled case or no applicable decision