# PIX Infractions and MED

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

::: tip 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](/en/webhooks-payloads).

---

## 3. Query Through API

### List MEDs

```http
GET /api/external/med
```

Required permission: `payment:read`.

### Get a MED

```http
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

```http
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

```json
{
  "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.

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

### Response

```json
{
  "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 Monetarie 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 Monetarie operation can register it in the case. Evidence remains archived for consultation, future review, and audit.

::: info Regulatory Submission
The defense text and final analyst opinion are used in the case response. Attachments and other evidence remain stored at Monetarie 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 |