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)

Permissions

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

Example

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

No native pagination

This endpoint queries the OnZ/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)

{
  "worked": true,
  "meds": [
    {
      "id": "MED20260307001",
      "type": "REFUND_REQUEST",
      "status": "ACKNOWLEDGED",
      "amount": 50000,
      "original_end_to_end_id": "E37839059202603071530000001",
      "created_at": "2026-03-07T18:00:00Z"
    },
    {
      "id": "MED20260305002",
      "type": "REFUND_CANCELLED",
      "status": "CLOSED",
      "amount": 15000,
      "original_end_to_end_id": "E37839059202603051200000003",
      "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 (OnZ/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 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

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.

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.

Response in dev/homologation environments

This endpoint queries the OnZ provider directly — it does not read from a local table. In dev/homologation it may return an empty array if the OnZ 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 OnZ/BACEN.

Provider failures return empty array

If there is a temporary OnZ 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)

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

Error Response (401)

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

Blocking disputed values

When a REFUND_REQUEST infraction is registered in ACKNOWLEDGED with value >R$ 1,000.00 (threshold configurable per account or merchant via med_configurations.min_threshold_amount), the backend creates a preventive block in TigerBeetle (med_cautelar_blocks row + TB phantom hold code 1032). The disputed amount becomes:

• Deducted from available returned by Balance
• Added to pending
• Preserved in balance (safe balance) until final decision

Infractions with value ≤R$ 1,000.00 or with e2e_id not found in your transactions receive automatic auto-deny (closing with AnalysisResult=DISAGREED) without creating a preventive block.

When the MED is resolved (CLOSED), the block is released:

• AnalysisResult=AGREED → amount transferred to the requester (PIX refund via PACS.004, E2E prefix D)
• AnalysisResult=DISAGREED → amount returns to the merchant's available

Subscribe to the pix.infraction.created, pix.refund.requested, and pix.infraction.resolved webhooks for real-time notification of each step. See Infractions (full flow) to understand the end-to-end cycle.

Auto-expiration: the worker Fluxiq.Workers.MedDefenseExpiration (cron */5 * * * *) auto-accepts blocks with deadline within the next 30 min whose defense has not yet been submitted — this avoids BACEN regulatory fines for not responding in time. See the "Deadlines" section in Infractions.