MED (特殊退款机制)

MED Endpoints 抗辩教程 Webhooks TrueHolder

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

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

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

MED 概念流程

将鼠标悬停在方框上以查看技术状态。点击直接跳转到详细说明各值的部分。

高层流程:

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

包含 infraction 的 webhook 示例

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

{
  "id": "MAGEN20251123104518DF75D20A8F",
  "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": "MAGEN IP",
  "receiverName": "MAGEN LTDA",
  "receiverDocument": "123456789010110",
  "endToEndId": "E18236120202511231046s1235ee7",
  "paidAt": "2025-11-23T10:46:26.986Z",
  "createdAt": "2025-11-23T10:45:18.403Z",
  "updatedAt": "2025-11-23T10: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": "2025-11-24T16:52:15.808Z",
    "createdAt": "2025-11-24T17:00:00.490Z",
    "updatedAt": "2025-11-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` 的值 (InfractionStatus)

值	描述
`WAITING_PSP`	等待提供商响应
`OPEN`	活跃且正在分析中
`ACKNOWLEDGED`	已被机构确认
`DEFENDED`	已提交抗辩
`ANSWERED`	已提供附加信息
`WAITING_ADJUSTMENTS`	等待文件
`CLOSED`	已通过最终决定解决
`CANCELLED`	在解决前被取消

`type` 的值 (InfractionType)

值	描述
`REFUND_REQUEST`	标准退款请求
`FRAUD`	与安全相关的投诉
`REFUND_CANCELLED`	取消先前的退款

`reportedBy` 的值

值	描述
`DEBITED_PARTICIPANT`	由付款方机构报告
`CREDITED_PARTICIPANT`	由收款方机构报告

`analysisResult` 的值

值	描述
`AGREED`	接受 infraction:将处理退款
`DISAGREED`	拒绝 infraction:不退款

收到 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 日志 (如果是提现)
谁在您的系统中执行了该操作
客户的 IP、设备、会话
该 payerDocument 的交易历史

决策:抗辩或接受

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

跟踪直到 `CLOSED`

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