# List MED

Lists MED (Special Refund Mechanism) processes associated with the account.

MED is a Central Bank mechanism for recovering funds in cases of fraud or operational failure in the PIX system.

## Endpoint

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

## Headers

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| `Authorization` | String | Yes | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | No | Set to `camelCase` to receive response fields in camelCase (default is snake_case) |

::: info Permissions
This endpoint requires the `payment:read` permission on the API Key. Keys without this permission receive HTTP 403.
:::

## Example

```bash
curl -X GET https://api.monetarie.com/api/external/med \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

::: warning No native pagination
This endpoint queries the PIX/BACEN provider in real time and **does not accept pagination parameters** (`page`/`per_page`/`limit`). All MEDs linked to the entity are returned in a single response. For large volumes, filter locally in your system after receiving the array.
:::

## Success Response (200)

```json
{
  "worked": true,
  "meds": [
    {
      "id": "MED20260307001",
      "type": "REFUND_REQUEST",
      "status": "ACKNOWLEDGED",
      "amount": 50000,
      "original_end_to_end_id": "E46026562202603071530000001",
      "created_at": "2026-03-07T18:00:00Z"
    },
    {
      "id": "MED20260305002",
      "type": "REFUND_CANCELLED",
      "status": "CLOSED",
      "amount": 15000,
      "original_end_to_end_id": "E46026562202603051200000003",
      "created_at": "2026-03-05T14:30:00Z"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `worked` | Boolean | `true` indicates operation success |
| `meds` | Array | List of MED processes |
| `meds[].id` | String | Unique MED identifier |
| `meds[].type` | String | MED type (see table below) |
| `meds[].status` | String | Current process status |
| `meds[].amount` | Integer | Value in **base units** (÷ 10,000 for BRL). `50000` = R$ 5.00 |
| `meds[].original_end_to_end_id` | String | E2E of the original PIX transaction |
| `meds[].created_at` | String | Opening date (ISO 8601) |

## MED Types

| Type | Description |
|------|-------------|
| `REFUND_REQUEST` | Refund request (fraud, scam, or agreement) |
| `REFUND_CANCELLED` | Cancellation of a previous refund request |

## MED Status

Values returned by the PIX provider (PIX/BACEN) in **UPPERCASE**. The API passes the value through as received - no normalization.

| Status | Description | Final decision |
|--------|-------------|----------------|
| `ACKNOWLEDGED` | MED received and acknowledged by the participant, under analysis | No - awaits defense or deadline |
| `CLOSED` | MED finalized by the participant | Yes - see `analysisResult` in [med-detail](/en/med-detail) to distinguish `AGREED` (refund executed) from `DISAGREED` (defense accepted, no refund) |
| `CANCELLED` | MED cancelled by the requester before analysis | Yes - no value was blocked or refunded |

::: warning Status is uppercase
MED statuses are always returned in **UPPERCASE**. If your filter expects lowercase (`pending`/`accepted`/`closed`), it will not match any row. This is a conscious difference from the PIX transaction statuses (lowercase) - MED follows the original BACEN convention.
:::

::: tip Correlation with the original transaction
Use the `original_end_to_end_id` field to locate the original PIX transaction that motivated the MED. Query via `GET /api/external/transactions/:id` or `GET /api/external/transactions/ref/:external_id` if you stored the `external_id`.
:::

::: info Response in dev/homologation environments
This endpoint queries the PIX provider directly - **it does not read from a local table**. In dev/homologation it may return an empty array if the PIX provider does not have test MEDs for the configured entity. In production, it returns the real list of MED processes for your account as passed by PIX/BACEN.
:::

::: warning Provider failures return empty array
If there is a temporary PIX provider outage, the endpoint returns `{"worked": true, "meds": []}` (silently, without 5xx). If you receive an empty array persistently while expecting MEDs, contact support to verify provider availability.
:::

## Success Response -- No MEDs (200)

```json
{
  "worked": true,
  "meds": []
}
```

## Error Response (401)

```json
{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}
```

::: warning Disputed values
When a MED requires analysis, the disputed amount may be temporarily reserved and appear in `pending` until the final decision.

When the MED is resolved (`CLOSED`):
- `AnalysisResult=AGREED` means the dispute was accepted and the refund was executed.
- `AnalysisResult=DISAGREED` means the dispute was rejected or the defense was accepted, with no refund.

Subscribe to [`pix.infraction.created`](/en/webhooks-payloads#pix-infraction-created), [`pix.refund.requested`](/en/webhooks-payloads#pix-refund-requested), [`pix.infraction.defense_submitted`](/en/webhooks-payloads#pix-infraction-defense-submitted), and [`pix.infraction.resolved`](/en/webhooks-payloads#pix-infraction-resolved) to track each step. To respond to a MED through the API, use `POST /api/external/med/:id/defense` with `payment:write`. See [Infractions](/en/infractions).
:::