列出 MED

列出与账户关联的 MED（特殊退款机制）流程。

MED 是巴西中央银行针对 PIX 系统中的欺诈或操作故障而设立的资金追回机制。

端点

GET /api/external/med

请求头

头	类型	必填	描述
Authorization	String	是	ApiKey {client_id}:{client_secret}
X-Key-Case	String	否	设为 camelCase 以使用 camelCase 接收响应字段（默认 snake_case）

权限

此端点需要 API Key 有 payment:read 权限。没有此权限的密钥收到 HTTP 403。

示例

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

无原生分页

此端点实时查询 PIX/BACEN provider,不接受分页参数（page/per_page/limit）。与实体关联的所有 MED 在单个响应中返回。对于大量数据,请在收到数组后在系统本地过滤。

成功响应 (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"
    }
  ]
}

字段	类型	描述
worked	Boolean	true 表示操作成功
meds	Array	MED 流程列表
meds[].id	String	MED 唯一标识符
meds[].type	String	MED 类型（见下表）
meds[].status	String	流程当前状态
meds[].amount	Integer	值,以基础单位（÷ 10.000 得到雷亚尔）。50000 = R$ 5,00
meds[].original_end_to_end_id	String	原始 PIX 交易的 E2E
meds[].created_at	String	开启日期（ISO 8601）

MED 类型

类型	描述
REFUND_REQUEST	退款请求（欺诈、诈骗或协议）
REFUND_CANCELLED	取消先前的退款请求

MED 状态

由 PIX provider（PIX/BACEN）以 UPPERCASE 返回。API 按原样传递值 - 无归一化。

状态	描述	最终决定
ACKNOWLEDGED	MED 由参与方接收并确认,正在分析中	否 - 等待抗辩或截止日期
CLOSED	MED 已由参与方完成	是 - 查看 med-detail 中的 analysisResult 以区分 AGREED（退款已执行）和 DISAGREED（抗辩被接受,无退款）
CANCELLED	MED 在分析前由请求方取消	是 - 无值被封锁或退回

状态为 uppercase

MED 状态始终以大写返回。如果您的过滤器期望小写（pending/accepted/closed）,将不会找到任何行。这是与 PIX 交易状态（小写）的有意差异 - MED 遵循 BACEN 原始约定。

与原始交易的相关性

使用字段 original_end_to_end_id 定位触发 MED 的原始 PIX 交易。如果您存储了 external_id,通过 GET /api/external/transactions/:id 或 GET /api/external/transactions/ref/:external_id 查询。

dev/homologacao 环境中的返回

此端点直接查询 PIX provider - 不从本地表读取。在 dev/homologacao 中,如果 PIX provider 没有为配置的实体提供测试 MED,可能返回空数组。在生产中,按 PIX/BACEN 传递的真实 MED 处理列表返回。

Provider 故障返回空数组

如果 PIX provider 有临时不可用,端点返回 {"worked": true, "meds": []}（静默,无 5xx）。如果您持续收到空数组而期望有 MED,请联系支持以检查 provider 是否不可用。

成功响应 -- 无 MED (200)

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

错误响应 (401)

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

争议金额

当 MED 需要分析时,争议金额可能会被临时保留并显示在 pending 中,直到最终决定。

当 MED 被解决（CLOSED）时:

• AnalysisResult=AGREED 表示争议被接受并执行退款。
• AnalysisResult=DISAGREED 表示争议被拒绝或抗辩被接受,无退款。

订阅 webhook pix.infraction.created、pix.refund.requested、pix.infraction.defense_submitted 和 pix.infraction.resolved。要通过 API 响应 MED,请使用 POST /api/external/med/:id/defense,权限为 payment:write。参见 违规。