跳到主要内容

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

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

生命周期​

RECEIVED -> CONTESTED -> PENDING_DECISION -> ACCEPTED / REJECTED / CANCELED
状态描述
RECEIVED已收到 MED。请在截止日期（holderAnswerDeadline）前做出回应。
CONTESTED已提交回应（AGREE 或 DISAGREE）并附上证据。
PENDING_DECISION回应已发送至银行，等待监管机构决定。
ACCEPTEDMED 已通过。金额将退还给付款人（全额或部分）。
REJECTEDMED 已驳回。金额保留在您的账户中。
CANCELEDMED 已由申诉方或监管机构取消。

最终结果​

当 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。

{
  "type": "pix.med.opened",
  "data": {
    "endToEndId": "E303062942026021812490000005QLMv",
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "status": "DELIVERED",
    "type": "REVERSAL",
    "method": "INVASION",
    "description": "I was scammed, did not receive the contracted product",
    "flow": "IN",
    "openedAt": "2026-02-18T19:34:14Z"
  }
}

状态历史​

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 进行争议（提交回应和上传证据）将在未来的更新中提供。目前，争议必须通过银行合作伙伴的渠道直接进行。

列出 MED​

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

返回租户的所有 MED，包括完整历史记录、退款信息和控制字段（holderAnswerStatus、holderAnswerDeadline、result）。

MED 比率监控​

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

参考阈值​

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

MED 策略​

请参阅策略和规则指南，了解如何配置自动封禁和比率限制。