MED (特殊退款机制)

央行针对 Pix 欺诈和骗局的安全网：当付款方所在机构发起退款请求时，你会在同一个交易 webhook 上收到通知，不用离开原有流程就能处理这笔争议。

MED Endpoints 抗辩教程 Webhooks TrueHolder

MED (特殊退款机制) 是巴西央行的一项程序,用于保护 Pix 用户在欺诈、骗局或未授权交易情况下的权益。

它作为安排的 "安全网" 运作:当识别到可疑活动时,付款方机构发起正式流程请求退款。

在 PayZu,MED 流程通过 webhook 交付,复用交易的同一个 callbackUrl。原交易的状态会被更新,infraction 对象会插入到 payload 中。

MED 概念流程

高层流程:

Pix 交易成功完成。
识别到问题 (欺诈、错误、未授权扣款)。
付款方机构在安排中发起 MED,webhook 到达时 status: "OPEN"。
收款银行收到通知,可能在分析期间冻结金额。
由机构分析争议 + Bacen 规则。
结果:接受 (AGREED,退还金额) 或拒绝 (DISAGREED,交易保持有效)。

包含 infraction 的 webhook 示例

Pix 交易遭遇 infraction 时收到的真实 payload 示例:

{
  "id": "PAYZU20260811K7M2X9QP4T000000",
  "type": "DEPOSIT",
  "status": "COMPLETED",
  "serviceFeeCharged": 1,
  "amount": 30,
  "clientReference": "d2b2a5ed-f1a4-477e-81da-9",
  "qrCodeText": "00020101021226870014br.gov.bcb.pix...",
  "payerName": "João da Silva",
  "payerDocument": "12345678901",
  "payerInstitutionName": "PAYZU IP",
  "receiverName": "PAYZU LTDA",
  "receiverDocument": "123456789010110",
  "endToEndId": "E18236120202608111046s1235ee7a91",
  "paidAt": "2026-08-11T10:46:26.986Z",
  "createdAt": "2026-08-11T10:45:18.403Z",
  "updatedAt": "2026-08-11T10:46:27.346Z",
  "callbackUrl": "https://seuwebhook.com",
  "infraction": {
    "id": "cmide759mb9i3s601bhwf6e",
    "protocol": "4dd32924-9b53-4408-af4b-6d3b4d7ac",
    "status": "OPEN",
    "type": "REFUND_REQUEST",
    "reportDetails": "Relato de fraude: transação contestada formalmente pelo pagador",
    "reportedBy": "DEBITED_PARTICIPANT",
    "analysisResult": null,
    "analysisDetails": null,
    "reportedAt": "2026-08-24T16:52:15.808Z",
    "createdAt": "2026-08-24T17:00:00.490Z",
    "updatedAt": "2026-08-24T17:00:00.490Z"
  }
}

`infraction` 对象的字段

字段	类型	描述
`id`	string	infraction 的唯一标识符
`protocol`	string	支付提供商的协议编号
`status`	InfractionStatus	infraction 的当前状态
`type`	InfractionType	infraction 的类型
`reportDetails`	string	争议原因的描述
`reportedBy`	ReportedBy	谁报告了 infraction
`analysisResult`	AnalysisResult \| null	最终决定 (待定时为 null)
`analysisDetails`	string \| null	决定的理由
`reportedAt`	string	报告时间
`expiresAt`	string \| null	解决期限
`createdAt`	string	创建日期
`updatedAt`	string	最后更新时间

status、type、reportedBy 和 analysisResult 的完整取值见术语表。

收到 infraction 时如何应对

检测回调

当 infraction 对象到达 payload 时,立即触发内部告警。Bacen 的期限很短,通常为 72 小时,沉默通常被解读为接受。

if (callback.infraction?.status === 'OPEN') {
  await alertOperations({
    transactionId: callback.id,
    infractionId: callback.infraction.id,
    expiresAt: callback.infraction.expiresAt,
    reportDetails: callback.infraction.reportDetails,
  });
}

调查

使用 GET /user/infractions/{id} 获取争议、原交易和期限的完整详情。与您的日志交叉核对:

付款前的 DICT 日志 (如果是 Pix 付款)
谁在您的系统中执行了该操作
客户的 IP、设备、会话
该 payerDocument 的交易历史

决策:抗辩或接受

场景	推荐决策
合法收款,有产品/服务交付证据	抗辩通过 `POST /user/infractions/{id}/defenses`
您这边确有欺诈嫌疑 (客户已被入侵)	接受 (不抗辩)。金额被退还,案件关闭。
您没有证据	视具体情况评估。无抗辩时,Bacen 倾向于接受异议。

跟踪直到 `CLOSED`

infraction 经过若干状态 (OPEN → ACKNOWLEDGED/DEFENDED → ANSWERED/WAITING_ADJUSTMENTS → CLOSED)。每次变更都会产生新的回调。最终结果在 status: "CLOSED" 时通过 analysisResult 给出。

完整生命周期

财务影响

当 infraction 为 AGREED 时

原交易(COMPLETED)经过 WAITING_FOR_REFUND,金额从余额扣除,交易最终变为 REFUNDED,并发送完成 webhook。实际退回的金额见回调中的 refundAmount,可能与原始 amount 不同。

当 infraction 为 DISAGREED 时

不退款:余额保持不变,交易仍为 COMPLETED。

下一步

抗辩教程术语表

MED (特殊退款机制)

本页内容