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.minhakonta.com/api/external/med \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

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)

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

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)

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

Error Response (401)

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

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, pix.refund.requested, pix.infraction.defense_submitted, and 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.