MED 详情

查询指定 MED（特殊退款机制）流程的完整详情。

端点

GET /api/external/med/:id

请求头

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

路径参数

参数	类型	必填	描述
id	String	是	MED 流程标识符

示例

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

成功响应 (200)

{
  "worked": true,
  "med": {
    "id": "MED20260307001",
    "type": "REFUND_REQUEST",
    "status": "ACKNOWLEDGED",
    "amount": 50000,
    "original_end_to_end_id": "E37839059202603071530000001",
    "reason": "Fraude reportada pelo pagador",
    "created_at": "2026-03-07T18:00:00Z"
  }
}

状态为 UPPERCASE

可能值：ACKNOWLEDGED、CLOSED、CANCELLED。按从 PIX provider（OnZ/BACEN）接收时原样传递 — 无归一化。详情见 med-list。

字段	类型	描述
worked	Boolean	true 表示操作成功
med.id	String	MED 唯一标识符
med.type	String	类型：REFUND_REQUEST 或 REFUND_CANCELLED
med.status	String	流程当前状态（ACKNOWLEDGED、CLOSED、CANCELLED）
med.amount	Integer	值,以基础单位（÷ 10.000 得到雷亚尔）。50000 = R$ 5,00
med.original_end_to_end_id	String	原始 PIX 交易的 E2E。用于与 GET /transactions/ref/:external_id 交叉查询
med.reason	String	请求方提供的原因（自由文本）。不可用时为 null
med.created_at	String	开启日期（ISO 8601 UTC）

通过 External API 未暴露的附加字段

OnZ/BACEN provider 返回的字段比此端点暴露的更多。有意在 serializer 中过滤掉的字段包括：

字段（OnZ）	描述	今天从哪获取
analysisResult	最终决定：AGREED 或 DISAGREED	Webhook pix.infraction.resolved
analysisDetails	决定的理由	Webhook pix.infraction.resolved
infractionType	REFUND_REQUEST 或 REFUND_CANCELLED	已在 med.type 中暴露
fraudType	SCAM、ACCOUNT_TAKEOVER、COERCION、FRAUDULENT_ACCESS、OTHER	Webhook pix.refund.requested（字段 fraud_category）
situationType	涉及的情况类型（BACEN 分类）	Merchant portal（/compliance）— External API 未提供
defenseDeadline	BACEN 的抗辩提交截止日期	Webhook pix.infraction.created

此省略是有意的（已知 gap）。如果您需要以编程方式消费这些字段,请联系 compliance@owem.com.br — 或使用列出的 webhook,它们始终在事件时刻携带相关字段。

参见 违规（完整流程） 了解 MED 与违规之间的关系。

值以子分表示,不是 BRL

字段 amount 以子分为单位（1 BRL = 10.000 子分）。值 50000 = R$ 5,00 — 不是 R$ 50.000。绝不要乘以 100 或使用 float。

错误响应 (404)

{
  "worked": false,
  "errors": {
    "not_found": "MED não encontrado"
  }
}

404 可能表示临时错误

如果 MED 存在于另一个通道（webhook、先前的列表）但此查询返回 404,可能是 OnZ provider 的临时故障。几秒后重试。如果超过 5 分钟持续,请联系支持。

后端将所有 provider 错误（包括超时和网络错误）转换为 HTTP 404 及 detail: "MED nao encontrado"。要区分"不存在"和"临时故障",请先查询 列出 MED 端点 — 如果 ID 出现在列表中但 detail 返回 404,那是临时的。

错误响应 (401)

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

实时跟踪（webhook）

webhook 事件 pix.refund.requested 和 pix.refund.completed 自 2026 年 4 月起由后端自动触发。建议订阅这些 webhook 以避免依赖轮询。在 GET /med/:id 或 GET /med 上轮询仍可作为替代方案工作。