Skip to content

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-Typeapplication/json
接口用途通知 MED 状态、资金冻结状态变更与退款执行结果

3. 请求头字段 ​

回调请求按 Adopay 统一规范携带签名与验签相关请求头,公共规则(HTTPS 传输、超时、失败处理、幂等、验签)详见 Webhook 规范。

4. 请求体字段 ​

公共字段(所有事件) ​

字段名类型是否必传说明
eventstring是事件类型,见下方事件类型对照。
occurredAtstring是事件发生时间,ISO 8601 UTC 时间字符串(yyyy-MM-ddTHH:mm:ssZ)。

全量 MED 字段(所有事件均携带) ​

所有事件在公共字段之外,均携带与 查询MED详情 data 完全一致的全量字段:字段名、类型、含义与详情接口相同,取值为事件发生(投递)时刻该 MED 的最新快照。

字段分组包含字段说明
概要字段medId、status、originSituationType、details、amount、analysisResult、dueTime、createdAt、updatedAtMED 概要信息,位于载荷顶层。
交易信息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 为空数组。

json
{
  "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)。

json
{
  "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 若发生多次退款执行(如补扣、分批退款),每次执行都会独立投递一条通知,不会合并。

字段名类型是否必传说明
chargebackobject是本次执行的退款记录,结构同详情接口 data.chargebacks[] 元素。
chargeback.statusstring是本次退款执行结果,固定为 SUCCESS(本事件仅在退款执行成功时投递)。
chargeback.infoTextstring是关于本次退款的附加信息,最大长度 255 个字符。
chargeback.errorDescriptorstring否本次退款执行失败时的错误描述;本事件中恒为 null。
chargeback.amountdecimal是本次退款金额。
chargeback.createdAtstring是本次退款创建时间,ISO 8601 UTC 时间字符串(yyyy-MM-ddTHH:mm:ssZ)。
chargeback.updatedAtstring是本次退款完成时间,ISO 8601 UTC 时间字符串(yyyy-MM-ddTHH:mm:ssZ)。

载荷中的 chargebacks 为截至本次执行的全部退款历史(含本次执行的记录)。退款执行结果如有后续变更,以 chargebacks 历史与 查询MED详情 为准。

json
{
  "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)。

json
{
  "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)。

json
{
  "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,资金保持冻结),商户补充资料后可重新提交分析。本事件无专属字段;打回的具体原因不随事件下发,如需了解请通过商户门户查看或联系平台。

json
{
  "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 为本次冻结时间。

json
{
  "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 为本次解冻时间。

json
{
  "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. 接入注意事项 ​

  1. 建议以 medId + event 或等价唯一键实现幂等;对 MED_REFUND_EXECUTED,建议再结合本次退款记录(如 chargeback.createdAt)作为幂等键,以区分同一 MED 的多次退款执行与重复投递。
  2. 所有时间字段(occurredAt、dueTime、createdAt、updatedAt、transactionDate、funds.frozenAt / funds.unfrozenAt、退款记录时间等)均为 ISO 8601 UTC 时间字符串(yyyy-MM-ddTHH:mm:ssZ),JSON 中使用字符串;允许为空的时间字段返回 null。
  3. 所有事件载荷均为全量结构,字段与 查询MED详情 的 data 一致,可直接从载荷取用全量信息;载荷反映事件发生时刻的快照,关键节点(如收到 MED_APPROVED、MED_REFUND_EXECUTED 后)仍建议调用详情接口复核。
  4. 收到 MED_APPROVED 仅代表退款流程开始;退款执行结果以 MED_REFUND_EXECUTED 事件及全量字段中的 chargebacks 为准。
  5. 资金事件、退款执行事件与状态事件独立投递、可能乱序到达,请勿以资金事件或退款执行事件推断 MED 终态。

返回 MED API 总览