PIX 违规和 MED

本页说明如何通过 Minha Konta API 跟踪并响应与 MED（特殊退款机制）相关的 PIX 争议。

摘要

PIX 违规是由付款方机构发起的争议。当案件需要分析时,您会收到 webhook,可以查询 MED,也可以在期限内提交带有说明和证据的抗辩。

1. 主要概念

概念	描述
PIX 违规	与已收到 PIX 相关的正式争议
MED	用于分析和可能退款的监管流程
预防性封锁	案件分析期间对争议金额的临时保留
抗辩	客户提交的说明,可附带证据
决定	案件最终结果,可能退款或释放金额

MED 是争议监管周期的一部分。案件分析期间可能影响可用余额。

2. 如何跟踪

使用 webhook 接收实时更新:

事件	使用场景
`pix.infraction.created`	争议已登记,需要跟踪
`pix.refund.requested`	金额进入 MED 争议流程
`pix.infraction.defense_submitted`	抗辩已登记
`pix.infraction.resolved`	争议已完成
`pix.refund.completed`	退款已执行
`pix.payout.returned`	退款入账已确认

查看 Webhook Payloads。

3. 通过 API 查询

http

GET /api/external/med
GET /api/external/med/{id}

所需权限: payment:read。

使用 webhook 或列表返回的 id 查询案件,并与争议 PIX 的 original_end_to_end_id 关联。

4. 通过 API 提交抗辩

http

POST /api/external/med/{id}/defense
Content-Type: application/json
Authorization: ApiKey {client_id}:{client_secret}
hmac: {hmac_sha512_signature}

所需权限: payment:write。

Body 必须是 JSON,并使用外部 API 其他 POST endpoint 相同的 HMAC 规则签名。

json

{
  "defense_text": "客户确认了该操作,并发送了服务证据。",
  "evidence": [
    {
      "type": "whatsapp",
      "url": "https://your-domain.example/evidence/med-123.png",
      "description": "确认持有人请求的对话截图",
      "source": "whatsapp",
      "filename": "conversation-med-123.png",
      "received_at": "2026-06-02T13:30:00Z"
    }
  ]
}

字段	类型	必填	描述
`defense_text`	string	是	抗辩文本和争议上下文
`evidence`	array	否	通过 URL 或描述引用的证据列表
`evidence[].type`	string	否	`url`, `document`, `image`, `screenshot`, `email`, `whatsapp` 或 `other`
`evidence[].url`	string	条件	客户托管证据的 `https` 或 `http` URL
`evidence[].description`	string	条件	无 URL 时的证据摘要

每个 evidence 项必须至少包含 url 或 description。每次提交最多接受 10 个证据引用。

证据

外部 API 保存文本和证据引用。二进制附件上传可在 Minha Konta 门户中完成,文件会被验证并存储用于分析和审计。

5. 门户和外部证据

同样的抗辩也可以在 Minha Konta 门户中处理。该方式允许直接上传 PDF、图片、截图、合同和客服历史等文件。

当证据通过 e-mail、WhatsApp、客服或 API 之外的其他渠道到达时,Minha Konta 运营团队可以将其登记到案件中。证据会被归档,用于查询、未来核查和审计。

6. 期限

响应期限会在与违规相关 webhook 的 defense_deadline 字段中发送。请在期限前响应,以便抗辩可以被正确分析和转交。

建议:

监控 pix.infraction.created 和 pix.refund.requested。
使用收到的 id 查询 MED。
一旦获得客户信息,通过 API 或门户提交抗辩。
在您的系统中保存 e2e_id, med_id 和提交时间。

7. 对账

使用 e2e_id 关联原始 PIX、违规 webhook、MED 记录以及可能的退款。

`analysis_result`	含义
`AGREED`	争议接受并执行退款
`DISAGREED`	抗辩接受或争议拒绝,无退款
`null`	案件取消或无适用决定

PIX 违规和 MED ​

1. 主要概念 ​

2. 如何跟踪 ​

3. 通过 API 查询 ​

4. 通过 API 提交抗辩 ​

5. 门户和外部证据 ​

6. 期限 ​

7. 对账 ​