/meds/{medId} 接口介绍

接口背景

/meds/{medId} 提供给商户的 MED 详情查询接口。返回特定 MED 的完整信息，并按语义分组：概要、争议交易、付款方与收款方、央行违规报告、资金冻结状态、分析信息以及退款（chargeback）历史。

查询MED列表 返回的记录是本接口的轻量投影，两者结构同构：列表项包含概要字段与 transaction、payer（不含银行账户）、payee、infractionReport 组；details、funds、analysis、chargebacks 仅在本接口返回。

接口请求地址

项目	内容
请求方式	GET
请求路径	/meds/{medId}
Content-Type	application/json
接口用途	查询 MED 详情

认证

使用 ES256 请求签名，必须携带 X-Merchant-Id、X-Timestamp、X-Nonce、Digest 和 Authorization。X-Merchant-Id 填写商户号，keyId 为密钥版本号，默认 v1。签名值为 DER 编码的 ECDSA 签名经标准 Base64 编码后的结果，具体规则见 请求签名。

示例中的时间戳、Nonce、摘要和签名占位符需按每次实际请求生成；签名串包含实际路径及原始 query，分页或筛选条件变化后必须重新签名。

接口请求字段

字段名	位置	类型	是否必填	说明
medId	Path	string	是	要查询的 MED 违规报告唯一标识符（平台案件号，medc 前缀 + 数字），最大长度 64 个字符。

请求示例

GET /meds/medc2874510938274639021 HTTP/1.1
Accept: application/json
X-Merchant-Id: <MERCHANT_ID>
X-Timestamp: <UNIX_TIMESTAMP_SECONDS>
X-Nonce: <UNIQUE_NONCE>
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

接口响应字段

接口使用统一的 status、msg、data 响应结构。MED 详情位于 data 中：顶层为概要字段，其余信息按语义分组。

概要字段

字段名	类型	是否必返	说明
status	int	是	响应码
msg	string	是	与 status 对应
data	object	成功必返	MED 详情；请求在验签或协议解析阶段失败时可能不返回。
data.medId	string	是	MED 唯一标识符，平台案件号（medc 前缀 + 数字），最大长度 64 个字符。
data.subMerchantNo	string	是	该 MED 所属二级商户号；直连商户固定为空字符串，可忽略。
data.status	string	是	MED 当前状态，取值见 MED API 总览的枚举值与状态说明。
data.originSituationType	string	是	引发该 MED 的情形类型，取值见 MED API 总览的枚举值与状态说明。
data.details	string	是	MED 描述，最大长度 500 个字符。
data.amount	decimal	是	MED 涉及的交易金额；整数部分最长 25 位，小数部分最长 4 位，且不为负数。
data.analysisResult	string	否	分析结果：ACCEPTED（已接受）或 REJECTED（已驳回）；尚未作出分析时为 null。
data.dueTime	string	否	举证截止时间，ISO 8601 UTC 时间字符串（yyyy-MM-ddTHH:mm:ssZ）；未设置时为 null。
data.createdAt	string	是	MED 记录创建时间，ISO 8601 UTC 时间字符串（yyyy-MM-ddTHH:mm:ssZ）。
data.updatedAt	string	是	MED 记录最后更新时间，ISO 8601 UTC 时间字符串（yyyy-MM-ddTHH:mm:ssZ）。

交易信息（data.transaction）

字段名	类型	是否必返	说明
data.transaction	object	是	引发该 MED 的 Pix 交易信息。
data.transaction.e2eId	string	是	Pix 端到端交易 ID，对应银行侧支付流水号，最大长度 64 个字符。
data.transaction.transactionDate	string	否	原交易发生时间，ISO 8601 UTC 时间字符串（yyyy-MM-ddTHH:mm:ssZ）；未提供时为 null。
data.transaction.merchantOrderNo	string	否	商户订单号，最大长度 64 个字符；未提供时为 null。
data.transaction.platOrderNo	string	否	平台订单号，最大长度 64 个字符；未提供时为 null。

付款方（data.payer）

付款方即发出 Pix 的一方，也就是 MED 发起人（争议交易的付款人）。

字段名	类型	是否必返	说明
data.payer	object	是	付款方信息。
data.payer.name	string	否	付款方姓名，最大长度 120 个字符；未提供时为 null。
data.payer.document	string	否	付款方 CPF/CNPJ，最大长度 14 个字符；未提供时为 null。
data.payer.email	string	是	付款方联系邮箱，最大长度 128 个字符。
data.payer.phone	string	是	付款方联系电话，最大长度 32 个字符。
data.payer.bankAccount	object	是	付款方的银行账户信息（来自 Pix 交易）。
data.payer.bankAccount.ispb	string	是	银行的 ISPB 代码，最大长度 8 个字符。
data.payer.bankAccount.bank	string	是	银行名称，最大长度 100 个字符。
data.payer.bankAccount.agency	string	是	银行支行代码，最大长度 10 个字符。
data.payer.bankAccount.account	string	是	账号，最大长度 20 个字符。
data.payer.bankAccount.document	string	是	账户持有人的证件号（CPF/CNPJ），最大长度 14 个字符。
data.payer.bankAccount.name	string	是	账户持有人姓名，最大长度 120 个字符。

收款方（data.payee）

收款方即接收 Pix 的一方。

字段名	类型	是否必返	说明
data.payee	object	是	收款方信息。
data.payee.name	string	否	收款方姓名，最大长度 120 个字符；未提供时为 null。
data.payee.document	string	否	收款方 CPF/CNPJ，最大长度 14 个字符；未提供时为 null。
data.payee.bankAccount	object	否	收款方的银行账户信息；当前版本不返回该组（预留字段），恒为 null。

违规报告（data.infractionReport）

字段名	类型	是否必返	说明
data.infractionReport	object	是	巴西央行违规报告信息。
data.infractionReport.id	string	否	违规报告标识符，最大长度 64 个字符；未提供时为 null。
data.infractionReport.status	string	是	违规报告状态：RECEIVED（已接收）、ANALYZED（已完成分析）或 CANCELLED（已取消）。
data.infractionReport.createdAt	string	否	违规报告创建时间，ISO 8601 UTC 时间字符串（yyyy-MM-ddTHH:mm:ssZ）；未提供时为 null。
data.infractionReport.creatorPsp	string	是	创建该违规报告的 PSP 的 ISPB 代码，最大长度 8 个字符。

资金状态（data.funds）

MED 创建后，争议交易金额即被冻结；裁决生效或 MED 取消后解冻。资金冻结与解冻会单独触发 MED_FUNDS_FROZEN / MED_FUNDS_UNFROZEN Webhook 事件，见 Webhook 回调。

字段名	类型	是否必返	说明
data.funds	object	是	商户资金冻结状态。
data.funds.status	string	是	资金状态，取值见下方 funds.status 枚举。
data.funds.amount	decimal	是	争议金额，与 data.amount 一致。
data.funds.frozenAt	string	否	冻结发生时间，ISO 8601 UTC 时间字符串；本接口当前不返回该时间（预留字段），恒为 null。
data.funds.unfrozenAt	string	否	解冻发生时间，ISO 8601 UTC 时间字符串；本接口当前不返回该时间（预留字段），恒为 null。

funds.status 资金状态枚举

值	说明
NOT_FROZEN	未冻结：尚未发生任何资金操作
PARTIALLY_FROZEN	部分冻结：冻结中金额未达争议金额
FROZEN	已冻结：冻结中金额已达争议金额
PARTIALLY_UNFROZEN	部分解冻：已解冻部分金额，仍有资金冻结中（未发生退款）
UNFROZEN	已解冻：冻结资金已全部解冻（未发生退款）
PARTIALLY_REFUNDED	部分退款：已发生退款，退款金额未达争议金额
FULLY_REFUNDED	全额退款：退款金额已达争议金额

发生过退款的 MED，即使随后解冻了剩余冻结金额，funds.status 仍为 PARTIALLY_REFUNDED 或 FULLY_REFUNDED。资金冻结时间的具体值以 Webhook 事件（MED_FUNDS_FROZEN / MED_FUNDS_UNFROZEN）中的 funds.frozenAt / funds.unfrozenAt 为准。

分析信息（data.analysis）

本组包含分析结论与分析过程信息；data.analysis.analysisResult 与概要字段 data.analysisResult 取值一致。

字段名	类型	是否必返	说明
data.analysis	object	是	分析信息；尚未作出分析时内部各字段为 null。
data.analysis.analysisResult	string	否	分析结论：ACCEPTED（商户接受 MED，同意退款）或 REJECTED（商户提出异议）；尚未作出分析时为 null。
data.analysis.analysisDetailsUser	string	否	用户提供的分析详情，最大长度 500 个字符。
data.analysis.analysisDetailsPsp	string	否	平台提供的分析详情，最大长度 500 个字符。

退款历史（data.chargebacks）

平台每执行一次退款操作，都会向商户投递一条 MED_REFUND_EXECUTED Webhook 事件（载荷包含本接口 data 的全部字段与本次退款记录），见 Webhook 回调。

字段名	类型	是否必返	说明
data.chargebacks	array	否	退款历史列表；未发生退款时为空数组。
data.chargebacks[].status	string	是	退款状态：PENDING、SUCCESS 或 REJECTED。
data.chargebacks[].infoText	string	是	关于退款的附加信息，最大长度 255 个字符。
data.chargebacks[].errorDescriptor	string	否	退款失败时的错误描述，最大长度 255 个字符。
data.chargebacks[].amount	decimal	是	退款金额。
data.chargebacks[].createdAt	string	是	退款创建时间，ISO 8601 UTC 时间字符串（yyyy-MM-ddTHH:mm:ssZ）。
data.chargebacks[].updatedAt	string	是	退款最后更新时间，ISO 8601 UTC 时间字符串（yyyy-MM-ddTHH:mm:ssZ）。

响应示例

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "medId": "medc2874510938274639021",
    "subMerchantNo": "",
    "status": "ACCEPTED_BY_PSP",
    "originSituationType": "SCAM_FRAUD",
    "details": "Detailed description of the dispute",
    "amount": 1000.50,
    "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": null,
      "unfrozenAt": null
    },
    "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:30:00Z"
      }
    ]
  }
}

响应错误码

• 响应状态

---

返回 MED API 总览