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

无原生分页

此端点实时查询 OnZ/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": "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"
    }
  ]
}

字段	类型	描述
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（OnZ/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 环境中的返回

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

Provider 故障返回空数组

如果 OnZ 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>"
  }
}

争议值的封锁

当 REFUND_REQUEST 违规在 ACKNOWLEDGED 中注册,值**>R$ 1.000,00**（通过 med_configurations.min_threshold_amount 按账户或 merchant 可配置）时,后端在 TigerBeetle 中创建预防性封锁（med_cautelar_blocks 行 + TB code 1032 phantom hold）。争议值保持：

• 从 余额 返回的 available 中扣除
• 累加到 pending
• 在最终决定之前保留在 balance（安全余额）中

值**≤R$ 1.000,00** 或 e2e_id 不在您的 transactions 中的违规接收自动auto-deny（关闭并带 AnalysisResult=DISAGREED）,不创建预防性封锁。

当 MED 被解决（CLOSED）时,封锁被释放：

• AnalysisResult=AGREED → 值转移给请求方（通过 PACS.004 的 PIX 退款,E2E 前缀 D）
• AnalysisResult=DISAGREED → 值返回到 merchant 的 available

订阅 webhook pix.infraction.created、pix.refund.requested 和 pix.infraction.resolved 以实时通知每个阶段。参见 违规（完整流程） 了解端到端循环。

自动过期：worker Fluxiq.Workers.MedDefenseExpiration（cron */5 * * * *）自动接受 deadline 在接下来 30 分钟内且抗辩尚未提交的封锁 — 这避免了未在截止日期前响应的 BACEN 监管罚款。参见 违规 中的"期限"部分。