争议 - 特殊退还机制（MED）

MED 的 REST 端点暂时下线

MED webhooks 处于启用状态：当争议发起或状态变更时，您会正常收到 pix.med.opened 和 pix.med.updated（参见 Webhooks）。

该模块的所有 REST 端点——查询 （GET /v1/accounts/{accountId}/pix/med）、抗辩（answer、decide、 evidence/*），以及按 tenant 的列表和统计 （/v1/backoffice/tenants/{tenantId}/meds 与 /med-stats）——在清算行迁移 期间均返回 HTTP 503，errorCode 为 "service_temporarily_unavailable"。 下方文档描述这些端点的契约，将在其重新启用后再次生效。

MED（Mecanismo Especial de Devolução）是付款人请求退还 PIX 付款的流程，通常因为疑似欺诈或操作失误。当您的账户收到 MED 申诉时，您需要在截止日期前进行争议或接受退还。

生命周期

OPEN -> PENDING_DECISION -> ACCEPTED / REJECTED / CANCELED

Webhook 的 data.status 使用五个取值的封闭词汇表。清算行的原始状态绝不 会被透传：不匹配下表的取值一律归为 PENDING_DECISION。

状态	描述
OPEN	已针对您的账户发起 MED，需在截止日期前回应。
PENDING_DECISION	回应已发送至银行，等待监管机构决定。清算行返回词汇表以外的状态时也使用该值。
ACCEPTED	MED 已通过。金额将退还给付款人（全额或部分）。
REJECTED	MED 已驳回。金额保留在您的账户中。
CANCELED	MED 已由申诉方或监管机构取消。

CONTESTED 状态和详细历史属于 REST 端点的契约（目前返回 503）——不会出现在 webhook 中。

最终结果

当 MED 关闭时，result 字段指示银行合作方的处理结果：

结果	描述
AGREED	银行同意退还
DISAGREED	银行不同意退还

部分退款

MED 可以产生多次部分退款。每次退款都有自己的 E2E（D 代码）和金额。refundedAmount 字段是所有退款的总和。

场景	示例
全额退款	originalAmount: 1000.00，refundedAmount: 1000.00
部分退款	originalAmount: 1000.00，refundedAmount: 300.00
无退款（无余额）	originalAmount: 1000.00，refundedAmount: 0.00

通过 Webhook 接收 MED

当 MED 被提出时，您会收到 pix.med.opened webhook。当状态更新时，收到 pix.med.updated。

{
  "id": "pix-med-opened-204cc938-da3d-4f04-baf3-0b2e6a2f1283",
  "type": "pix.med.opened",
  "occurredAt": "2026-02-18T19:34:14.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "tenantId": "tenant-yourcompany",
    "accountId": "773107de-...",
    "originalEndToEnd": "E303062942026021812490000005QLMv",
    "amount": 1000.00,
    "reasonCode": "FRAUD",
    "claimMessage": "I was scammed, did not receive the contracted product",
    "openedAtIso": "2026-02-18T19:34:14.000000000Z",
    "status": "OPEN"
  }
}

pix.med.updated 的字段集合相同，但不含 claimMessage 和 openedAtIso， status 反映此次状态变更。

状态历史

API 维护所有状态变更的完整历史记录。每条记录包含：

{
  "history": [
    { "status": "RECEIVED", "rawStatus": "DELIVERED", "timestamp": "2026-02-18T19:34:14Z", "description": "MED received" },
    { "status": "CONTESTED", "rawStatus": "CONTESTED", "timestamp": "2026-02-19T10:00:00Z", "description": "Answer: DISAGREE" },
    { "status": "PENDING_DECISION", "rawStatus": "ACKNOWLEDGED", "timestamp": "2026-02-20T14:00:00Z" },
    { "status": "REJECTED", "rawStatus": "REJECTED", "timestamp": "2026-02-23T09:00:00Z" }
  ]
}

争议 MED

通过 API 进行争议（提交回应和上传证据）使用 POST /v1/accounts/{accountId}/pix/med/{medId}/answer、/decide 和 /evidence/* 端点——如本页顶部所述，它们目前均返回 503。在此期间，争议 必须通过银行合作伙伴的渠道直接进行。

查询与列出 MED

按账户：

GET /v1/accounts/{accountId}/pix/med

按 tenant（后台）：

GET /v1/backoffice/tenants/{tenantId}/meds

重新启用后，它们会返回 MED 及完整历史记录、退款信息和控制字段（holderAnswerStatus、holderAnswerDeadline、result）。

MED 比率监控

GET /v1/backoffice/tenants/{tenantId}/med-stats?days=30

返回按日汇总的统计数据：

字段	描述
pixInCount	当日的 PIX IN 交易笔数
pixInAmount	PIX IN 总金额
medCount	针对当日交易的 MED 数量
medAmount	MED 总金额
quantityRatePercent	medCount / pixInCount * 100
amountRatePercent	medAmount / pixInAmount * 100

参考阈值

下列阈值属于运营参考（用于面板和商务跟进），并非 API 行为：不会由此自动 产生任何错误码或冻结。按比率触发的自动动作在策略与规则中配置。

比率	状态	描述
< 0.4%	绿色	健康水平
0.4% - 1.0%	黄色	需要关注，密切监控
> 1.0%	红色	比率偏高，可能需要采取措施

MED 策略

请参阅策略和规则指南，了解如何配置：

• 自动冻结：对超过指定金额的 MED 自动冻结余额。
• 最大比率：MED/PIX-In 比例上限及其自动动作。