MED API（特别退款机制）

最后更新时间： 2026-09-29

MED（Mecanismo Especial de Devolução，特别退款机制）API 用于管理 PIX 欺诈争议与退回请求，并遵循巴西中央银行（Banco Central do Brasil）的监管规定。该 API 允许您对与账户 PIX 交易相关的 MED 违规报告（infraction reports）进行查询、分析与处理。

在合作商 API 下，您是代表名下的二级商户操作 MED：每笔 MED 均归属于您的合作商账户下的唯一一个二级商户，所有响应与 Webhook 事件都会携带该二级商户号（subMerchantNo），便于您将记录路由到对应的二级商户。

一、什么是 MED？

Adopay 处理多种类型的 MED，包括：

欺诈（Fraud）： 在标识符 SCAM_FRAUD 下处理诈骗与欺诈活动。
未授权交易（Unauthorized Transactions）： 涵盖未经授权情况下的账户访问。
胁迫性犯罪（Coercive Crimes）： 适用于在威胁或胁迫下进行的交易。
欺诈性授权（Fraudulent Authorization）： 涉及未经授权的访问与交易批准。
其他情形（Other Situations）： 涵盖其他 MED 类别。

二、核心概念

MED（Mecanismo Especial de Devolução）： 巴西中央银行监管的 Pix 欺诈退款机制。
二级商户（Sub-merchant）： 合作商账户下入驻的商户。每笔 MED 均归属于唯一一个二级商户，由其商户号（subMerchantNo）标识。
违规报告（Infraction Report）： 由 BCB 发起的针对某笔 Pix 交易的违规报告。
退款（Chargeback / Refund）： 当 MED 被批准后发起的退款流程。
证据材料清单（Evidence Requirements）： Adopay 根据 MED 所属行业与商户类型匹配的材料要求（通用材料 + 行业专属材料，平台型 / PSP 商户另含平台类附加材料）。
证据文件（Response File）： 按材料类型上传、用于支撑分析决策的文件（如交易凭证、沟通记录等）。

涉及的各方

角色	说明
创建方 PSP（Creator PSP）	创建该违规报告的金融机构。
付款方（Payer）	发出 PIX 的一方（潜在的欺诈受害者）。
收款方（Payee）	接收 PIX 的一方（潜在的欺诈者）。

三、MED 状态流转

mermaid

flowchart TB
    S([ ]) -->|"违规报告下发（RECEIVED）"| WAITING["WAITING<br/>待合作商处理"]
    WAITING ~~~ EVI["EVIDENCE_REQUIRED<br/>待补充资料"]
    WAITING -->|提交分析：同意退款| A["ACCEPTED_BY_USER<br/>已同意退款"]
    WAITING -->|提交分析：提出异议| R["REJECTED_BY_USER<br/>已提出异议"]
    EVI -->|补件后重新提交| U["UNDER_REVIEW<br/>平台审核中"]
    A -->|进入平台审核| U
    R -->|进入平台审核| U
    U -->|平台打回异议提交| EVI
    U -->|审核成立| ACC["ACCEPTED_BY_PSP<br/>审核成立 · 执行退款"]
    U -->|审核不成立| REJ["REJECTED_BY_PSP<br/>审核不成立 · 不退款"]
    WAITING -->|用户撤销| CU["CANCELLED_BY_USER<br/>用户撤销 · 解冻"]
    WAITING -->|平台撤销| CP["CANCELLED_BY_PSP<br/>平台撤销 · 解冻"]
    ACC -->|结案| CLOSED["CLOSED<br/>已结案（终态）"]
    REJ -->|结案| CLOSED
    CU -->|结案| CLOSED
    CP -->|结案| CLOSED
    CLOSED --> E([ ])

处理时限： MED 收款侧分析阶段（WAITING / EVIDENCE_REQUIRED 中的材料上传与分析提交）须在监管规定的 7 个自然日内完成，即举证截止时间（dueTime）之前。

超时处理： 超过 dueTime 合作商仍未提交时，案件不再等待合作商，由平台代为提交并进入平台审核（UNDER_REVIEW）。合作商未响应不当然等同于 MED 成立，最终结果以 PSP/结算机构的审核结论为准。

终态： 每笔 MED 最终都会到达终态：先得出审核结论或撤销（ACCEPTED_BY_PSP / REJECTED_BY_PSP / CANCELLED_BY_USER / CANCELLED_BY_PSP），资金处理（扣款或退还）完毕后统一进入 CLOSED，此后状态不再变化。撤销可发生在审核结论作出之前的任一未结案状态，图中以 WAITING 为代表画出。

状态说明

WAITING（待处理）： MED 案件等待合作商处理（上传证据文件并提交分析）。
EVIDENCE_REQUIRED（待补充资料）： 平台打回了合作商的异议提交，要求补充资料；合作商可补充文件后重新提交分析。
UNDER_REVIEW（平台审核中）： 合作商已提交分析结论（同意退款或提出异议），或平台已代为提交，平台审核中；审核期间保持本状态，直到出审核结果。
ACCEPTED_BY_USER（合作商已同意退款）： 合作商已提交同意退款的分析结论。
REJECTED_BY_USER（合作商已提出异议）： 合作商已提交提出异议的分析结论。
ACCEPTED_BY_PSP（审核成立）： 平台审核结果为 MED 成立并执行退款；资金进入扣款/退款处理。
REJECTED_BY_PSP（审核不成立）： 平台审核结果为 MED 不成立；通常不退款。
CANCELLED_BY_USER（用户撤销）： 付款用户/投诉发起方撤销本次 MED 申请；不退款（如有冻结，解冻）。
CANCELLED_BY_PSP（平台撤销）： 平台撤销或终止本次 MED 处理；不退款（如有冻结，解冻）。
CLOSED（已结案）： 资金处理（扣款或退还）完毕后结案，终态。

交互时序（含央行违规报告状态与资金流）

mermaid

sequenceDiagram
    autonumber
    participant BCB as 巴西央行（BCB）
    participant CPSP as 创建方 PSP（发起方）
    participant PSP as 平台（PSP）
    participant MER as 合作商

    CPSP->>BCB: 提交违规报告
    BCB->>PSP: 下发违规报告
    Note over BCB: infractionReportStatus = RECEIVED
    Note over PSP: 创建 MED，status = WAITING
    PSP->>PSP: 冻结合作商资金（争议交易金额）
    PSP-->>MER: Webhook：MED_CREATED

    MER->>PSP: 查询列表 / 获取详情
    MER->>PSP: 查询 MED 所属行业的材料类型
    PSP-->>MER: 返回材料项（evidenceType + 要求）
    opt 仅合作商提出异议（REJECTED）需先上传证据文件
        loop 返回的材料项
            MER->>PSP: 提交对应文件（evidenceType + file）
        end
    end
    alt 在举证截止时间（dueTime）前提交
        MER->>PSP: 提交分析（ACCEPTED / REJECTED）
    else 超时未响应
        PSP->>PSP: 平台代为提交（未响应不当然等同于 MED 成立）
    end
    Note over PSP: status = UNDER_REVIEW（平台审核中）

    PSP->>PSP: 平台审核
    alt 打回异议提交
        rect rgb(255, 236, 210)
            Note over PSP: status = EVIDENCE_REQUIRED，合作商资金保持冻结
            PSP-->>MER: Webhook：MED_ANALYSIS_REJECTED
            Note right of MER: 补充资料后重新提交分析
        end
    else 审核结果：MED 成立
        rect rgb(219, 240, 219)
            Note over BCB: infractionReportStatus = ANALYZED
            Note over PSP: status = ACCEPTED_BY_PSP（审核成立）
            PSP-->>MER: Webhook：MED_APPROVED
            PSP->>PSP: 解冻并扣除合作商资金（执行退款 chargeback）
            PSP-->>MER: Webhook：MED_REFUND_EXECUTED（每执行一次退款投递一次）
        end
    else 审核结果：MED 不成立
        rect rgb(250, 230, 230)
            Note over BCB: infractionReportStatus = ANALYZED
            Note over PSP: status = REJECTED_BY_PSP（审核不成立）
            PSP-->>MER: Webhook：MED_REJECTED
            PSP->>PSP: 解冻合作商资金
        end
    end

    opt 裁决作出前
        alt 付款用户/投诉发起方撤销
            CPSP->>BCB: 撤销 MED 申请
            BCB-->>PSP: infractionReportStatus = CANCELLED
            Note over PSP: status = CANCELLED_BY_USER（用户撤销）
        else 平台撤销或终止处理
            Note over PSP: status = CANCELLED_BY_PSP（平台撤销）
        end
        PSP-->>MER: Webhook：MED_CANCELLED
        PSP->>PSP: 解冻合作商资金
    end

    opt 资金处理完毕后
        PSP->>PSP: 结案
        Note over PSP: status = CLOSED（终态，不单独投递 Webhook）
    end

四、认证

所有 MED API 接口使用 ES256 请求签名，必须携带 X-Merchant-Id、X-Timestamp、X-Nonce、Digest 和 Authorization，具体规则见请求签名。

五、接口列表

接口	说明
查询MED列表	使用基于游标的分页列出所有 MED 违规报告，支持按日期范围、二级商户、状态及违规报告状态过滤
查询MED详情	获取特定 MED 的完整详情，包括收付双方账户、资金冻结状态、分析信息与退款历史
查询证据材料要求	查询 MED 所属行业对应的材料清单及完成情况
上传证据文件	按 `evidenceType` 为 MED 上传证据文件（PDF、图片等）
提交分析结果	提交分析后进入 `UNDER_REVIEW`（平台审核中），由平台审核并给出结果（`ACCEPTED_BY_PSP` / `REJECTED_BY_PSP`），异议提交可能被打回 `EVIDENCE_REQUIRED`
Webhook 回调	MED 状态、资金冻结与退款执行的异步通知事件（载荷为全量结构，字段与详情接口一致）

六、枚举值与状态说明

分析结果（Analysis Result）

值	说明
`ACCEPTED`	MED 已接受 —— 将处理退款
`REJECTED`	MED 已驳回 —— 不予退款
`null`	待分析 —— 尚未作出决定

MED 状态（MED Status）

值	说明
`WAITING`	待处理：案件等待合作商处理（上传证据文件并提交分析）
`EVIDENCE_REQUIRED`	待补充资料：平台打回了合作商的异议提交，合作商可补充文件后重新提交分析
`UNDER_REVIEW`	平台审核中：合作商已提交分析结论（或平台已代为提交），平台审核中，直到出审核结果
`ACCEPTED_BY_USER`	合作商已提交同意退款的分析结论
`REJECTED_BY_USER`	合作商已提交提出异议的分析结论
`ACCEPTED_BY_PSP`	审核成立：平台审核结果为 MED 成立并同意执行退款
`REJECTED_BY_PSP`	审核不成立：平台审核结果为 MED 不成立
`CANCELLED_BY_USER`	用户撤销：付款用户/投诉发起方撤销本次 MED 申请
`CANCELLED_BY_PSP`	平台撤销：平台撤销或终止本次 MED 处理
`CLOSED`	已结案：资金处理（扣款或退还）完毕后结案，终态

违规报告状态（Infraction Report Status）

值	说明
`RECEIVED`	报告已被接收
`ANALYZED`	报告已完成分析
`CANCELLED`	报告已被取消

发起方认定的争议类型（Origin Situation Type）

值	说明
`SCAM_FRAUD`	诈骗或欺诈情形
`UNAUTHORIZED_TRANSACTION`	未授权交易
`COERCIVE_CRIME`	胁迫性犯罪交易
`FRAUDULENT_ACCESS_AND_AUTHORIZATION`	欺诈性访问与授权
`OTHER`	其他类型情形
`UNKNOWN`	未知情形类型

七、业务规则

数据隔离

MED 按合作商及其二级商户双重隔离，合作商仅能查看与操作名下二级商户（由 subMerchantNo 标识）的 MED。
禁止跨合作商、跨二级商户的可见性。

证据材料匹配

Adopay 通过 medId 确定 MED 所属的 subMerchantNo，合作商无需另行指定商户号。
每个 MED 只对应一个行业与商户类型；材料清单由通用材料、行业专属材料（及平台型 / PSP 商户的平台类附加材料）组成，按平台配置的顺序返回。
模板编码、模板版本及匹配过程属于 Adopay 内部信息，不在接口响应中返回。
提交 REJECTED（驳回）裁决时，Adopay 校验所有必填（REQUIRED）材料是否已上传对应文件，材料不完整时提交被拒绝，MED 保持原状态（WAITING 或 EVIDENCE_REQUIRED）；提交 ACCEPTED（接受）裁决时无需上传证据文件。CONDITIONAL（条件必填）材料仅提示，不参与强制校验。
证据文件上传与分析提交须在举证截止时间（dueTime）前完成，超期后上传与提交接口均会拒绝。
超过 dueTime 未提交的 MED，由平台代为提交并进入平台审核（UNDER_REVIEW）；合作商未响应不当然等同于 MED 成立，最终结果以 PSP/结算机构的审核结论为准，案件最终都会进入终态（CLOSED）。

八、Webhook 事件

MED 状态与资金冻结状态变更、以及每次退款操作的执行，都会触发 webhook 事件：MED_CREATED、MED_APPROVED、MED_REJECTED、MED_CANCELLED、MED_ANALYSIS_REJECTED（平台打回异议提交，案件进入 EVIDENCE_REQUIRED），资金事件 MED_FUNDS_FROZEN、MED_FUNDS_UNFROZEN，以及退款执行事件 MED_REFUND_EXECUTED（每执行一次退款即投递一次）。所有事件载荷均为全量结构：携带该 MED 所属二级商户号（subMerchantNo），并包含与查询MED详情 data 一致的全量字段。详见 Webhook 回调。

九、最佳实践

定期轮询新的 MED（例如每 15 分钟一次）。
订阅 Webhook，而非仅依赖轮询。
提交驳回裁决前查询证据材料要求，按 evidenceType 上传文件并确认 data.complete 为 true（complete 仅统计必填 REQUIRED 材料）；接受裁决无需上传证据文件。
关注 dueTime，在举证截止时间前完成材料上传与分析提交。
记录所有分析与决定，以满足合规与审计要求。

十、合规要求（巴西中央银行）

解决时限： MED 收款侧分析阶段须在监管规定的 7 个自然日内完成。
合作商未响应： 合作商未响应不当然等同于 MED 成立，最终结果以 PSP/结算机构的审核结论为准。
申诉期： 允许 10 天 的 MED 申诉期。
文档留存： 所有决策必须留存文档。
通知义务： 必须将决定通知所有相关方。

账户

商户

收款

付款

PixKey管理

对账文件

MED

Webhook 事件

MED API（特别退款机制）

一、什么是 MED？

二、核心概念

涉及的各方

三、MED 状态流转

状态说明

交互时序（含央行违规报告状态与资金流）

四、认证

五、接口列表

六、枚举值与状态说明

分析结果（Analysis Result）

MED 状态（MED Status）

违规报告状态（Infraction Report Status）

发起方认定的争议类型（Origin Situation Type）

七、业务规则

数据隔离

证据材料匹配

八、Webhook 事件

九、最佳实践

十、合规要求（巴西中央银行）

MED API（特别退款机制） ​

一、什么是 MED？ ​

二、核心概念 ​

涉及的各方 ​

三、MED 状态流转 ​

状态说明 ​

交互时序（含央行违规报告状态与资金流） ​

四、认证 ​

五、接口列表 ​

六、枚举值与状态说明 ​

分析结果（Analysis Result） ​

MED 状态（MED Status） ​

违规报告状态（Infraction Report Status） ​

发起方认定的争议类型（Origin Situation Type） ​

七、业务规则 ​

数据隔离 ​

证据材料匹配 ​

八、Webhook 事件 ​

九、最佳实践 ​

十、合规要求（巴西中央银行） ​

MED API（特别退款机制）

一、什么是 MED？

二、核心概念

涉及的各方

三、MED 状态流转

状态说明

交互时序（含央行违规报告状态与资金流）

四、认证

五、接口列表

六、枚举值与状态说明

分析结果（Analysis Result）

MED 状态（MED Status）

违规报告状态（Infraction Report Status）

发起方认定的争议类型（Origin Situation Type）

七、业务规则

数据隔离

证据材料匹配

八、Webhook 事件

九、最佳实践

十、合规要求（巴西中央银行）