MED 回调通知接口文档
1. 通知接口背景
MED(Mecanismo Especial de Devolução,特别退款机制)是由巴西中央银行监管的 Pix 欺诈退款机制。当 MED 状态、资金冻结状态发生变化或退款操作执行时,Adopay 会通过 HTTP 异步回调向商户发送对应的事件通知。
MED 共有八种事件类型。所有事件的载荷均为全量结构:除公共字段与事件专属字段外,每个事件都携带与 查询MED详情 data 完全一致的字段集合(概要字段与 transaction、payer、payee、infractionReport、funds、analysis、chargebacks 各组)——详情接口中有什么字段,Webhook 载荷中就有什么字段。Webhook 是 Adopay 主动通知,不使用普通 API 的 status、msg、data 响应外层。
2. 回调地址和请求方式
| 项目 | 内容 |
|---|---|
| 请求方式 | POST |
| 请求地址 | 商户配置的 MED Webhook 回调地址,必须是完整的 HTTPS 地址 |
| Content-Type | application/json |
| 接口用途 | 通知 MED 状态、资金冻结状态变更与退款执行结果 |
3. 请求头字段
回调请求按 Adopay 统一规范携带签名与验签相关请求头,公共规则(HTTPS 传输、超时、失败处理、幂等、验签)详见 Webhook 规范。
4. 请求体字段
公共字段(所有事件)
| 字段名 | 类型 | 是否必传 | 说明 |
|---|---|---|---|
event | string | 是 | 事件类型,见下方事件类型对照。 |
occurredAt | string | 是 | 事件发生时间,ISO 8601 UTC 时间字符串(yyyy-MM-ddTHH:mm:ssZ)。 |
全量 MED 字段(所有事件均携带)
所有事件在公共字段之外,均携带与 查询MED详情 data 完全一致的全量字段:字段名、类型、含义与详情接口相同,取值为事件发生(投递)时刻该 MED 的最新快照。
| 字段分组 | 包含字段 | 说明 |
|---|---|---|
| 概要字段 | medId、status、originSituationType、details、amount、analysisResult、dueTime、createdAt、updatedAt | MED 概要信息,位于载荷顶层。 |
| 交易信息 | transaction | 引发该 MED 的 Pix 交易信息(含 e2eId、transactionDate、merchantOrderNo、platOrderNo)。 |
| 付款方 | payer | 付款方信息及其银行账户。 |
| 收款方 | payee | 收款方信息及其银行账户。 |
| 违规报告 | infractionReport | 央行违规报告信息。 |
| 资金状态 | funds | 商户资金冻结状态。 |
| 分析信息 | analysis | 分析结论与分析过程信息。 |
| 退款历史 | chargebacks | 退款(chargeback)执行历史。 |
各字段的类型、长度限制与取值说明详见 查询MED详情 的响应字段,此处不再重复。
事件专属字段
MED_REFUND_EXECUTED 在全量字段之外额外携带专属字段 chargeback(本次退款执行记录),见第 5 节各事件说明。
事件类型对照
| 事件类型 | 触发时机 | 事件触发时的 MED 状态 |
|---|---|---|
MED_CREATED | 违规报告被接收并登记 | WAITING |
MED_APPROVED | 平台裁决确认 MED 成立,进入退款流程 | ACCEPTED_BY_PSP |
MED_REFUND_EXECUTED | 每执行一次退款(chargeback)操作即触发一次;同一 MED 多次执行退款会多次投递 | 不改变 MED 状态(触发时为 ACCEPTED_BY_PSP) |
MED_REJECTED | 平台裁决确认 MED 不成立 | REJECTED_BY_PSP |
MED_CANCELLED | 裁决作出前取消 MED(发起方撤销或平台终止) | CANCELLED_BY_USER / CANCELLED_BY_PSP |
MED_ANALYSIS_REJECTED | 平台打回商户提交的异议分析(如资料不足) | EVIDENCE_REQUIRED |
MED_FUNDS_FROZEN | 冻结商户争议交易资金 | 状态类事件之外独立触发,不改变 MED 状态 |
MED_FUNDS_UNFROZEN | 解冻商户争议交易资金 | 状态类事件之外独立触发,不改变 MED 状态 |
5. 各事件专属字段与示例
以下各小节仅描述事件的触发逻辑与专属字段(全量 MED 字段所有事件均携带,不再逐个列出);示例为完整载荷,可直接作为对接联调参考。
5.1 MED_CREATED(违规报告登记)
MED 创建时触发。无专属字段;全量字段中 status 为 WAITING、analysisResult 为 null、chargebacks 为空数组。
{
"event": "MED_CREATED",
"medId": "medc2874510938274639021",
"occurredAt": "2026-01-15T14:30:00Z",
"status": "WAITING",
"originSituationType": "SCAM_FRAUD",
"details": "Detailed description of the dispute",
"amount": 1000.50,
"analysisResult": null,
"dueTime": "2026-01-31T23:59:59Z",
"createdAt": "2026-01-15T14:30:00Z",
"updatedAt": "2026-01-15T14:30:00Z",
"transaction": {
"e2eId": "E1234567820240115143000123",
"transactionDate": "2026-01-15T14:30:12Z",
"merchantOrderNo": "PIX20260816000001",
"platOrderNo": "P5nosqyWAQsQZNtYa5OW"
},
"payer": {
"name": "João Silva",
"document": "12345678901",
"email": "user@example.com",
"phone": "+5511999999999",
"bankAccount": {
"ispb": "12345678",
"bank": "Banco Example",
"agency": "1234",
"account": "567890",
"document": "12345678901",
"name": "João Silva"
}
},
"payee": {
"name": "John Doe",
"document": "12345678000195",
"bankAccount": null
},
"infractionReport": {
"id": "report-456",
"status": "RECEIVED",
"createdAt": "2026-01-15T14:30:00Z",
"creatorPsp": "12345678"
},
"funds": {
"status": "FROZEN",
"amount": 1000.50,
"frozenAt": "2026-01-15T14:30:05Z",
"unfrozenAt": null
},
"analysis": {
"analysisResult": null,
"analysisDetailsUser": null,
"analysisDetailsPsp": null
},
"chargebacks": []
}5.2 MED_APPROVED(MED 成立)
平台裁决确认 MED 成立、进入退款流程时触发。无专属字段;全量字段中 status 为 ACCEPTED_BY_PSP、analysisResult 为 ACCEPTED。本事件仅代表退款流程开始,此后每执行一次退款操作都会单独投递一条 MED_REFUND_EXECUTED(见 5.3)。
{
"event": "MED_APPROVED",
"medId": "medc2874510938274639021",
"occurredAt": "2026-01-16T10:30:00Z",
"status": "ACCEPTED_BY_PSP",
"originSituationType": "SCAM_FRAUD",
"details": "Detailed description of the dispute",
"amount": 1000.50,
"analysisResult": "ACCEPTED",
"dueTime": "2026-01-31T23:59:59Z",
"createdAt": "2026-01-15T14:30:00Z",
"updatedAt": "2026-01-16T10:30:00Z",
"transaction": {
"e2eId": "E1234567820240115143000123",
"transactionDate": "2026-01-15T14:30:12Z",
"merchantOrderNo": "PIX20260816000001",
"platOrderNo": "P5nosqyWAQsQZNtYa5OW"
},
"payer": {
"name": "João Silva",
"document": "12345678901",
"email": "user@example.com",
"phone": "+5511999999999",
"bankAccount": {
"ispb": "12345678",
"bank": "Banco Example",
"agency": "1234",
"account": "567890",
"document": "12345678901",
"name": "João Silva"
}
},
"payee": {
"name": "John Doe",
"document": "12345678000195",
"bankAccount": null
},
"infractionReport": {
"id": "report-456",
"status": "ANALYZED",
"createdAt": "2026-01-15T14:30:00Z",
"creatorPsp": "12345678"
},
"funds": {
"status": "FULLY_REFUNDED",
"amount": 1000.50,
"frozenAt": "2026-01-15T14:30:05Z",
"unfrozenAt": "2026-01-16T10:30:00Z"
},
"analysis": {
"analysisResult": "ACCEPTED",
"analysisDetailsUser": "User analysis details",
"analysisDetailsPsp": "PSP confirmed fraudulent transaction"
},
"chargebacks": []
}5.3 MED_REFUND_EXECUTED(退款执行)
Adopay 每执行一次该 MED 的退款(chargeback)操作,即向商户投递一次本事件;同一 MED 若发生多次退款执行(如补扣、分批退款),每次执行都会独立投递一条通知,不会合并。
| 字段名 | 类型 | 是否必传 | 说明 |
|---|---|---|---|
chargeback | object | 是 | 本次执行的退款记录,结构同详情接口 data.chargebacks[] 元素。 |
chargeback.status | string | 是 | 本次退款执行结果,固定为 SUCCESS(本事件仅在退款执行成功时投递)。 |
chargeback.infoText | string | 是 | 关于本次退款的附加信息,最大长度 255 个字符。 |
chargeback.errorDescriptor | string | 否 | 本次退款执行失败时的错误描述;本事件中恒为 null。 |
chargeback.amount | decimal | 是 | 本次退款金额。 |
chargeback.createdAt | string | 是 | 本次退款创建时间,ISO 8601 UTC 时间字符串(yyyy-MM-ddTHH:mm:ssZ)。 |
chargeback.updatedAt | string | 是 | 本次退款完成时间,ISO 8601 UTC 时间字符串(yyyy-MM-ddTHH:mm:ssZ)。 |
载荷中的 chargebacks 为截至本次执行的全部退款历史(含本次执行的记录)。退款执行结果如有后续变更,以 chargebacks 历史与 查询MED详情 为准。
{
"event": "MED_REFUND_EXECUTED",
"medId": "medc2874510938274639021",
"occurredAt": "2026-01-16T10:35:00Z",
"status": "ACCEPTED_BY_PSP",
"originSituationType": "SCAM_FRAUD",
"details": "Detailed description of the dispute",
"amount": 1000.50,
"analysisResult": "ACCEPTED",
"dueTime": "2026-01-31T23:59:59Z",
"createdAt": "2026-01-15T14:30:00Z",
"updatedAt": "2026-01-16T10:35:00Z",
"transaction": {
"e2eId": "E1234567820240115143000123",
"transactionDate": "2026-01-15T14:30:12Z",
"merchantOrderNo": "PIX20260816000001",
"platOrderNo": "P5nosqyWAQsQZNtYa5OW"
},
"payer": {
"name": "João Silva",
"document": "12345678901",
"email": "user@example.com",
"phone": "+5511999999999",
"bankAccount": {
"ispb": "12345678",
"bank": "Banco Example",
"agency": "1234",
"account": "567890",
"document": "12345678901",
"name": "João Silva"
}
},
"payee": {
"name": "John Doe",
"document": "12345678000195",
"bankAccount": null
},
"infractionReport": {
"id": "report-456",
"status": "ANALYZED",
"createdAt": "2026-01-15T14:30:00Z",
"creatorPsp": "12345678"
},
"funds": {
"status": "FULLY_REFUNDED",
"amount": 1000.50,
"frozenAt": "2026-01-15T14:30:05Z",
"unfrozenAt": "2026-01-16T10:30:00Z"
},
"analysis": {
"analysisResult": "ACCEPTED",
"analysisDetailsUser": "User analysis details",
"analysisDetailsPsp": "PSP confirmed fraudulent transaction"
},
"chargebacks": [
{
"status": "SUCCESS",
"infoText": "Chargeback successful",
"errorDescriptor": null,
"amount": 1000.50,
"createdAt": "2026-01-16T09:20:00Z",
"updatedAt": "2026-01-16T10:35:00Z"
}
],
"chargeback": {
"status": "SUCCESS",
"infoText": "Chargeback successful",
"errorDescriptor": null,
"amount": 1000.50,
"createdAt": "2026-01-16T09:20:00Z",
"updatedAt": "2026-01-16T10:35:00Z"
}
}5.4 MED_REJECTED(MED 不成立)
平台裁决确认 MED 不成立时触发。无专属字段;全量字段中 status 为 REJECTED_BY_PSP、analysisResult 为 REJECTED,资金解冻另行投递 MED_FUNDS_UNFROZEN(见 5.8)。
{
"event": "MED_REJECTED",
"medId": "medc2874510938274639021",
"occurredAt": "2026-01-16T09:20:00Z",
"status": "REJECTED_BY_PSP",
"originSituationType": "SCAM_FRAUD",
"details": "Detailed description of the dispute",
"amount": 1000.50,
"analysisResult": "REJECTED",
"dueTime": "2026-01-31T23:59:59Z",
"createdAt": "2026-01-15T14:30:00Z",
"updatedAt": "2026-01-16T09:20:00Z",
"transaction": {
"e2eId": "E1234567820240115143000123",
"transactionDate": "2026-01-15T14:30:12Z",
"merchantOrderNo": "PIX20260816000001",
"platOrderNo": "P5nosqyWAQsQZNtYa5OW"
},
"payer": {
"name": "João Silva",
"document": "12345678901",
"email": "user@example.com",
"phone": "+5511999999999",
"bankAccount": {
"ispb": "12345678",
"bank": "Banco Example",
"agency": "1234",
"account": "567890",
"document": "12345678901",
"name": "João Silva"
}
},
"payee": {
"name": "John Doe",
"document": "12345678000195",
"bankAccount": null
},
"infractionReport": {
"id": "report-456",
"status": "ANALYZED",
"createdAt": "2026-01-15T14:30:00Z",
"creatorPsp": "12345678"
},
"funds": {
"status": "UNFROZEN",
"amount": 1000.50,
"frozenAt": "2026-01-15T14:30:05Z",
"unfrozenAt": "2026-01-16T09:20:00Z"
},
"analysis": {
"analysisResult": "REJECTED",
"analysisDetailsUser": "User analysis details",
"analysisDetailsPsp": "PSP confirmed fraudulent transaction"
},
"chargebacks": []
}5.5 MED_CANCELLED(MED 取消)
发起方在裁决作出前取消 MED 时触发。无专属字段;全量字段中 status 为 CANCELLED_BY_USER、analysisResult 为 null,资金解冻另行投递 MED_FUNDS_UNFROZEN(见 5.8)。
{
"event": "MED_CANCELLED",
"medId": "medc2874510938274639021",
"occurredAt": "2026-01-17T12:00:00Z",
"status": "CANCELLED_BY_USER",
"originSituationType": "SCAM_FRAUD",
"details": "Detailed description of the dispute",
"amount": 1000.50,
"analysisResult": null,
"dueTime": "2026-01-31T23:59:59Z",
"createdAt": "2026-01-15T14:30:00Z",
"updatedAt": "2026-01-17T12:00:00Z",
"transaction": {
"e2eId": "E1234567820240115143000123",
"transactionDate": "2026-01-15T14:30:12Z",
"merchantOrderNo": "PIX20260816000001",
"platOrderNo": "P5nosqyWAQsQZNtYa5OW"
},
"payer": {
"name": "João Silva",
"document": "12345678901",
"email": "user@example.com",
"phone": "+5511999999999",
"bankAccount": {
"ispb": "12345678",
"bank": "Banco Example",
"agency": "1234",
"account": "567890",
"document": "12345678901",
"name": "João Silva"
}
},
"payee": {
"name": "John Doe",
"document": "12345678000195",
"bankAccount": null
},
"infractionReport": {
"id": "report-456",
"status": "CANCELLED",
"createdAt": "2026-01-15T14:30:00Z",
"creatorPsp": "12345678"
},
"funds": {
"status": "UNFROZEN",
"amount": 1000.50,
"frozenAt": "2026-01-15T14:30:05Z",
"unfrozenAt": "2026-01-17T12:00:00Z"
},
"analysis": {
"analysisResult": null,
"analysisDetailsUser": null,
"analysisDetailsPsp": null
},
"chargebacks": []
}5.6 MED_ANALYSIS_REJECTED(异议分析被平台打回)
当通过 提交分析结果 提交的异议分析(REJECTED)被平台打回时触发(如资料不足,需商户补充后重新提交)。被打回的分析不会生效,MED 状态变为 EVIDENCE_REQUIRED(全量字段中 status 为 EVIDENCE_REQUIRED、analysisResult 为 null,资金保持冻结),商户补充资料后可重新提交分析。本事件无专属字段;打回的具体原因不随事件下发,如需了解请通过商户门户查看或联系平台。
{
"event": "MED_ANALYSIS_REJECTED",
"medId": "medc2874510938274639021",
"occurredAt": "2026-01-16T15:00:00Z",
"status": "EVIDENCE_REQUIRED",
"originSituationType": "SCAM_FRAUD",
"details": "Detailed description of the dispute",
"amount": 1000.50,
"analysisResult": null,
"dueTime": "2026-01-31T23:59:59Z",
"createdAt": "2026-01-15T14:30:00Z",
"updatedAt": "2026-01-16T15:00:00Z",
"transaction": {
"e2eId": "E1234567820240115143000123",
"transactionDate": "2026-01-15T14:30:12Z",
"merchantOrderNo": "PIX20260816000001",
"platOrderNo": "P5nosqyWAQsQZNtYa5OW"
},
"payer": {
"name": "João Silva",
"document": "12345678901",
"email": "user@example.com",
"phone": "+5511999999999",
"bankAccount": {
"ispb": "12345678",
"bank": "Banco Example",
"agency": "1234",
"account": "567890",
"document": "12345678901",
"name": "João Silva"
}
},
"payee": {
"name": "John Doe",
"document": "12345678000195",
"bankAccount": null
},
"infractionReport": {
"id": "report-456",
"status": "RECEIVED",
"createdAt": "2026-01-15T14:30:00Z",
"creatorPsp": "12345678"
},
"funds": {
"status": "FROZEN",
"amount": 1000.50,
"frozenAt": "2026-01-15T14:30:05Z",
"unfrozenAt": null
},
"analysis": {
"analysisResult": null,
"analysisDetailsUser": "User analysis details",
"analysisDetailsPsp": null
},
"chargebacks": []
}5.7 MED_FUNDS_FROZEN(资金冻结)
平台冻结商户争议交易资金时触发(裁决作出前,或裁决成立后补充冻结),用于财务侧对账,与 MED_CREATED 独立投递。无专属字段;全量字段中 funds.status 为投递时刻的资金状态(冻结中金额达到争议金额为 FROZEN,未达到为 PARTIALLY_FROZEN,此前已发生退款则为 PARTIALLY_REFUNDED,取值见 查询MED详情 的 funds.status 枚举),funds.frozenAt 为本次冻结时间。
{
"event": "MED_FUNDS_FROZEN",
"medId": "medc2874510938274639021",
"occurredAt": "2026-01-15T14:30:05Z",
"status": "WAITING",
"originSituationType": "SCAM_FRAUD",
"details": "Detailed description of the dispute",
"amount": 1000.50,
"analysisResult": null,
"dueTime": "2026-01-31T23:59:59Z",
"createdAt": "2026-01-15T14:30:00Z",
"updatedAt": "2026-01-15T14:30:05Z",
"transaction": {
"e2eId": "E1234567820240115143000123",
"transactionDate": "2026-01-15T14:30:12Z",
"merchantOrderNo": "PIX20260816000001",
"platOrderNo": "P5nosqyWAQsQZNtYa5OW"
},
"payer": {
"name": "João Silva",
"document": "12345678901",
"email": "user@example.com",
"phone": "+5511999999999",
"bankAccount": {
"ispb": "12345678",
"bank": "Banco Example",
"agency": "1234",
"account": "567890",
"document": "12345678901",
"name": "João Silva"
}
},
"payee": {
"name": "John Doe",
"document": "12345678000195",
"bankAccount": null
},
"infractionReport": {
"id": "report-456",
"status": "RECEIVED",
"createdAt": "2026-01-15T14:30:00Z",
"creatorPsp": "12345678"
},
"funds": {
"status": "FROZEN",
"amount": 1000.50,
"frozenAt": "2026-01-15T14:30:05Z",
"unfrozenAt": null
},
"analysis": {
"analysisResult": null,
"analysisDetailsUser": null,
"analysisDetailsPsp": null
},
"chargebacks": []
}5.8 MED_FUNDS_UNFROZEN(资金解冻)
裁决生效或 MED 取消后解冻商户争议交易资金时触发,用于财务侧对账,与 MED_APPROVED / MED_REJECTED / MED_CANCELLED 独立投递。无专属字段;全量字段中 funds.status 为投递时刻的资金状态(全部解冻为 UNFROZEN,仍有资金冻结中为 PARTIALLY_UNFROZEN,此前已发生退款则为 PARTIALLY_REFUNDED),funds.unfrozenAt 为本次解冻时间。
{
"event": "MED_FUNDS_UNFROZEN",
"medId": "medc2874510938274639021",
"occurredAt": "2026-01-16T10:30:00Z",
"status": "ACCEPTED_BY_PSP",
"originSituationType": "SCAM_FRAUD",
"details": "Detailed description of the dispute",
"amount": 1000.50,
"analysisResult": "ACCEPTED",
"dueTime": "2026-01-31T23:59:59Z",
"createdAt": "2026-01-15T14:30:00Z",
"updatedAt": "2026-01-16T10:30:00Z",
"transaction": {
"e2eId": "E1234567820240115143000123",
"transactionDate": "2026-01-15T14:30:12Z",
"merchantOrderNo": "PIX20260816000001",
"platOrderNo": "P5nosqyWAQsQZNtYa5OW"
},
"payer": {
"name": "João Silva",
"document": "12345678901",
"email": "user@example.com",
"phone": "+5511999999999",
"bankAccount": {
"ispb": "12345678",
"bank": "Banco Example",
"agency": "1234",
"account": "567890",
"document": "12345678901",
"name": "João Silva"
}
},
"payee": {
"name": "John Doe",
"document": "12345678000195",
"bankAccount": null
},
"infractionReport": {
"id": "report-456",
"status": "ANALYZED",
"createdAt": "2026-01-15T14:30:00Z",
"creatorPsp": "12345678"
},
"funds": {
"status": "UNFROZEN",
"amount": 1000.50,
"frozenAt": "2026-01-15T14:30:05Z",
"unfrozenAt": "2026-01-16T10:30:00Z"
},
"analysis": {
"analysisResult": "ACCEPTED",
"analysisDetailsUser": "User analysis details",
"analysisDetailsPsp": "PSP confirmed fraudulent transaction"
},
"chargebacks": []
}6. 商户响应要求
商户应在 3 秒内完成响应并返回 HTTP 200—299;超时或非成功响应视为投递失败。同一事件可能因重试收到多次投递,商户必须可安全处理重复投递(幂等)。
公共规则(传输、超时、失败处理、幂等、验签)详见 Webhook 规范。
7. 接入注意事项
- 建议以
medId+event或等价唯一键实现幂等;对MED_REFUND_EXECUTED,建议再结合本次退款记录(如chargeback.createdAt)作为幂等键,以区分同一 MED 的多次退款执行与重复投递。 - 所有时间字段(
occurredAt、dueTime、createdAt、updatedAt、transactionDate、funds.frozenAt/funds.unfrozenAt、退款记录时间等)均为 ISO 8601 UTC 时间字符串(yyyy-MM-ddTHH:mm:ssZ),JSON 中使用字符串;允许为空的时间字段返回null。 - 所有事件载荷均为全量结构,字段与 查询MED详情 的
data一致,可直接从载荷取用全量信息;载荷反映事件发生时刻的快照,关键节点(如收到MED_APPROVED、MED_REFUND_EXECUTED后)仍建议调用详情接口复核。 - 收到
MED_APPROVED仅代表退款流程开始;退款执行结果以MED_REFUND_EXECUTED事件及全量字段中的chargebacks为准。 - 资金事件、退款执行事件与状态事件独立投递、可能乱序到达,请勿以资金事件或退款执行事件推断 MED 终态。
返回 MED API 总览