争议与 MED(Pix 退单)

Pix 付款在结算之后仍可能被提出争议。在 Pix 上,对应的渠道是 MED(BACEN 的 Mecanismo Especial de Devolução,即特别退款机制): 付款人向自己的银行申请撤销一笔他们声称属于欺诈、诈骗或误操作的交易。当针对您的某笔收款发起 MED 时,Liqfy 会为其开立一个 MED 案件,在案件处理期间从您的账户中冻结该金额,并通过 webhook、电子邮件和控制台通知您——这样您就不会等到月底才发现损失。

这与退款不同,退款是由您主动发起的冲正。MED 则由付款人在其银行一侧发起。

本页所述的一切均可通过 API(/v1/med/cases)、官方 SDK (medCases 资源)以及控制台中的 Disputes & MED Cases 面板使用。三者 读取和修改的是同一个案件。

#生命周期概览

                 charge paid
                      │
        MED opened by the payer's bank
                      │
                      ▼
   med_case "open"  ── amount held from your account,
                      │  charge becomes "disputed", refund blocked
          ┌───────────┴──────────────┐
          ▼                          ▼
   you accept                 you appeal (+ evidence)
          │                          │
          ▼                          ▼
     "accepted"                 "appealed"
   (loss taken)                      │
                         ┌───────────┴───────────┐
                         ▼                       ▼
                    "rejected"               "closed"
                  (MED upheld,          (in your favor, or
                   loss taken)       closed without refund)

案件也可以直接从 open 进入 closed——例如付款人撤回索赔,或在您回应之前裁决已有利于您。其他并非由您自己的操作引起的状态转换,请参见案件状态。

#MED 开立时会发生什么

1. 创建 MED 案件(med_case,id 为 med_…),关联到被争议的收款 (charge_id,ch_…)。初始状态为 open。
2. Liqfy 从您的账户中冻结该金额。 争议金额会从您的运营余额中扣除 (余额可能变为负数),并在案件处理期间保持冻结。如果 案件以有利于您的结果结束,金额会退回;如果您败诉,金额此前已预留。平台以无资金影响方式手动登记的案件不会扣除任何金额。
3. 收款变为 disputed。 公开的收款状态 (状态词汇表)从 paid 变为 disputed。处于 disputed 状态的收款无法退款——退款会造成重复 冲正(您的退款 + 银行执行的 MED)。如果案件以有利于您的结果结束, 收款会恢复为 paid。
4. 您会收到通知,通过下列所有渠道。

重复或不一致的报告。 如果某笔收款已有一个相同金额(或相同提供商账本引用)的案件, 又收到了新的报告;或者新报告与该收款的其他 MED 合计将超过收款金额,Liqfy 会将其记录 以供内部审核,不会发生任何资金变动,并且您看不到它——没有 案件、没有 webhook、没有电子邮件。如果平台判定这是一个独立的 MED,案件 会在那时出现(带有 med_case.created),金额也在那时冻结。

#您如何收到通知

这三个事件的载荷和签名见 Webhooks。

MED 不会触发 charge.* webhook。 该收款已支付;MED 不是收款 失败,也不是退款——MED 开立、胜诉或败诉时,charge.failed 和 charge.refunded 都不会发送。 请订阅 med_case.created、med_case.updated 和 med.resolved。案件处理期间重新读取收款(GET /v1/charges/{id})会显示 status: "disputed"。

Webhook 只是信号;API 才是事实来源。 结果通知 (med.resolved,以及针对 accepted / rejected / closed 的 med_case.updated)可能 无法送达:发布失败的 MED 案件事件不会重试。请使用 GET /v1/med/cases 进行对账(例如每天一次, 按 created_after 过滤),并以 API 返回的 status + money_outcome 为最终结果。

#案件状态

并非由您自己的操作引起的状态转换:

• open → appealed:当提供商报告案件正在审核中时。此时 appealed_at 会被填写,appeal_reason 保持为 null,且该案件无法再通过 API 申诉或接受。
• open / appealed → accepted:当提供商报告索赔已被接受,或 平台记录损失时;appealed → rejected:当申诉败诉 或平台记录损失时。
• closed → accepted:当平台更正一个被错误关闭的案件时: 金额会被再次扣除,money_outcome 变为 lost,并发送 med_case.updated。

当案件处于 open 或 appealed 状态时,money_outcome 为 null,之后则表示 资金的最终去向:

仅凭 closed 并不意味着您胜诉。请始终读取 money_outcome。

有些结果会在付款人银行或 BACEN 对案件作出裁决后立即生效;另一些 则需要更长时间才能确认,在确认之前案件保持当前状态(open 或 appealed)。 提供商报告的有利结果可能会先经过 Liqfy 团队的 审核——撤回的索赔则一定会经过审核——提供商报告的不利 裁决同样会先由团队处理,然后案件才会变更。

#截止时间

response_deadline(ISO 8601,UTC)是回应案件的截止时间。当截止时间已告知 Liqfy 时 会填写该字段,否则为 null。它会在 med_case.created 中发送,并在每次读取时返回。请计划在截止时间之前尽早 提交申诉(连同证据)——裁决不会等您。

#您的抗辩:申诉、接受和证据

当案件处于 open 状态时,您可以选择以下两种方式之一:

• 申诉(POST /v1/med/cases/{id}/appeal)——您以书面理由对 MED 提出异议 (reason:去除首尾空白后至少 5 个字符,原始字符最多 2,000 个——2,000 的上限适用于 API 密钥调用)。案件变为 appealed。
• 接受(POST /v1/med/cases/{id}/accept)——您放弃异议。案件变为 accepted,金额保持扣除。

证据(发票、交付证明、与买家的沟通记录——任何能证明该 收款合法的材料)通过下文的三步上传流程附加。您可以在申诉之前或之后 附加证据;请在截止时间之前附加。

重要——您的抗辩会发往何处。 您的申诉、您的接受以及每个已确认上传的证据 文件都会立即记录在 Liqfy 平台上, 案件也会立即变更。当被争议收款的支付提供商账户支持接收 MED 抗辩时,它们还会被异步转发给该支付提供商;不支持时,它们仅记录在 Liqfy 平台上。 只有 10 MB 以内的 PDF、PNG、JPEG、WEBP 或 GIF 格式证据会被转发。转发并 不决定案件结果:官方裁决会通过 MED 渠道送达 Liqfy, 并反映在案件上(status、money_outcome)以及上述 webhook 中。

#API

所有路由均使用您的 API 密钥,且只能看到您自己的案件。规范路径为 /v1/med/cases;/v1/infractions 是提供相同路由的别名。

Authorization: Bearer lq_live_...

规范的认证请求头是 Authorization: Bearer <key>。旧版 apikey: <key> 形式仍作为兼容方式可用,但新集成应使用 Authorization: Bearer。

案件 {id} 接受 med_… id(去掉 med_ 前缀的同一 id 也可以)。

#med_case 对象

{
  "id": "med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10",
  "object": "med_case",
  "type": "med",
  "status": "open",
  "amount": 15000,
  "currency": "BRL",
  "charge_id": "ch_6b0f4c1e-2a8d-4c1b-9d0e-1f2a3b4c5d6e",
  "charge_metadata": { "order_id": "PED-10442" },
  "customer_name": "Maria Silva",
  "reason": "Payer reports a scam",
  "response_deadline": "2026-09-30T23:59:59.000Z",
  "evidence_requested_at": null,
  "appeal_reason": null,
  "appealed_at": null,
  "evidence_count": 0,
  "money_outcome": null,
  "opened_at": "2026-09-23T14:02:11.000Z",
  "closed_at": null,
  "created_at": "2026-09-23T14:02:12.000Z",
  "updated_at": "2026-09-23T14:02:12.000Z"
}

#列出案件

curl "https://api.liqfy.com.br/v1/med/cases?status=open&limit=25" \
  -H "Authorization: Bearer $LIQFY_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10", "object": "med_case", "status": "open", "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10"
}

案件按最新优先排序(created_at 降序)。当 has_more 为 true 时,将 next_cursor 作为 starting_after 传入以读取下一页;最后一页的 next_cursor 为 null。 status、type 或 limit 的值未知、日期格式错误、 starting_after 不是您的案件,或 starting_after/charge_id 超过 140 个字符时,返回 400——这七个文档化的过滤器从不会被静默 忽略。额外参数 q、types 和 page 属于控制台,在 API 密钥下会被 静默忽略。

#获取案件

curl "https://api.liqfy.com.br/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10" \
  -H "Authorization: Bearer $LIQFY_API_KEY"

返回 med_case 对象,如果该案件在您的账户中不存在则返回 404。

#对案件提出申诉

curl -X POST "https://api.liqfy.com.br/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/appeal" \
  -H "Authorization: Bearer $LIQFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Order #8812 was delivered on 2026-09-20; signed delivery receipt attached."}'

reason 为必填项:去除首尾空白后至少 5 个字符,原始字符最多 2,000 个 (2,000 的上限仅对 API 密钥调用以 400 强制执行;在控制台中,较长的 文本会被截断为前 2,000 个字符)。返回 200 及更新后的案件 (status: "appealed"、appeal_reason 和 appealed_at 已填写)。只有 open 案件 可以申诉:其他任何状态均返回 400。为单独人工处理而开立的案件 即使仍处于 open 状态也会返回 400——这类案件由 平台直接裁定,不接受抗辩。在您账户中不存在的案件返回 404。

#接受案件

curl -X POST "https://api.liqfy.com.br/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/accept" \
  -H "Authorization: Bearer $LIQFY_API_KEY"

无请求体。返回 200 及更新后的案件(status: "accepted", money_outcome: "lost")。只有 open 案件可以接受:其他任何状态均返回 400——并且与申诉一样,处于单独人工处理中的案件即使处于 open 状态也会返回 400。在您账户中不存在的案件返回 404。接受操作不可撤销。

#上传证据

文件通过短时有效的签名 URL 直接上传到存储;它们永远不会经过 API 请求体。限制:每个文件 10 MB;类型为 image/png、image/jpeg、image/jpg、 image/webp、image/gif 和 application/pdf。

步骤 1——申请上传 URL。 声明文件名、以字节为单位的精确大小(JSON 数字)及其类型。也接受 camelCase 形式 fileName、fileSize 和 mimeType:

curl -X POST "https://api.liqfy.com.br/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/evidence" \
  -H "Authorization: Bearer $LIQFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_name": "delivery-receipt.pdf", "file_size": 52341, "mime_type": "application/pdf"}'

201 Created:

{
  "id": "0b8e6f52-7c3d-4e1a-9f40-2d6c8a1b5e77",
  "object": "med_case_evidence_upload",
  "upload_url": "https://storage.example.com/…?X-Amz-Signature=…",
  "upload_method": "PUT",
  "upload_headers": { "Content-Type": "application/pdf", "Content-Length": "52341" },
  "expires_in": 900
}

步骤 2——在 expires_in 秒(15 分钟)内将文件 PUT 到 upload_url,并 严格使用 upload_headers 中的请求头。签名绑定了类型和大小,因此 不同的 Content-Type 或不同大小的文件会被存储拒绝。不要 向该 URL 发送您的 API 密钥(或任何 Authorization 请求头)——URL 本身就是 凭证。

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @delivery-receipt.pdf

(curl --data-binary 会自动为您发送文件的 Content-Length;它必须与 步骤 1 中的 file_size 一致。)

步骤 3——确认上传。 Liqfy 会检查文件是否确实已到达,并将 证据标记为已上传:

curl -X POST "https://api.liqfy.com.br/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/evidence/0b8e6f52-7c3d-4e1a-9f40-2d6c8a1b5e77/complete" \
  -H "Authorization: Bearer $LIQFY_API_KEY"

200 OK 及证据对象:

{
  "id": "0b8e6f52-7c3d-4e1a-9f40-2d6c8a1b5e77",
  "object": "med_case_evidence",
  "file_name": "delivery-receipt.pdf",
  "file_size": 52341,
  "mime_type": "application/pdf",
  "uploaded_by": "merchant",
  "created_at": "2026-09-23T15:10:02.000Z",
  "uploaded_at": "2026-09-23T15:10:09.000Z",
  "view_url": "https://storage.example.com/…?X-Amz-Signature=…"
}

complete 是幂等的:对已确认的文件再次调用会返回相同的证据。 它是此接口面中唯一幂等的路由——其他路由不接受 Idempotency-Key, 也不会去重。如果 PUT 尚未完成(或 URL 已过期),则返回 409 及 error.code EVIDENCE_NOT_UPLOADED——请重新申请 URL(步骤 1)并再次上传。 从未确认的证据对 API 而言不存在:它不会被列出,不计入 evidence_count,也不会被转发给提供商。

官方 SDK 可通过一次调用完成这三个步骤——参见 SDK。

#列出证据

curl "https://api.liqfy.com.br/v1/med/cases/med_3f1c2b9e-0d7a-4a55-9a51-6f0e3c1d2b10/evidence" \
  -H "Authorization: Bearer $LIQFY_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "0b8e6f52-7c3d-4e1a-9f40-2d6c8a1b5e77", "object": "med_case_evidence", "file_name": "delivery-receipt.pdf", "...": "..." }
  ]
}

仅返回已确认的证据,按最新优先排序。uploaded_by 为 merchant(您)、 partner 或 platform(Liqfy 团队)。view_url 是有效期为 5 分钟的签名下载链接——重新获取列表即可得到新的链接。它可为空:当账户关闭 文档存储时为 null。

#错误

错误使用标准的错误格式:一个 error 对象(type、code、 message,以及适用时的 param / details)外加 request_id,后者也会在 X-Request-Id 请求头中发送。MED 案件特有的错误:

#SDK

官方 SDK 将相同的路由公开为 medCases 资源(Python 中为 med_cases, .NET 中为 MedCases),另外还提供一个执行三个上传步骤的 uploadEvidence 辅助方法:

import { LiqfyClient } from '@liqfy/node';
import { readFile } from 'node:fs/promises';

const client = new LiqfyClient({ apiKey: process.env.LIQFY_API_KEY!, baseUrl: 'https://api.liqfy.com.br' });

const { data, has_more, next_cursor } = await client.medCases.list({ status: 'open' });

for (const medCase of data) {
  await client.medCases.uploadEvidence(medCase.id, await readFile('delivery-receipt.pdf'), {
    fileName: 'delivery-receipt.pdf',
    mimeType: 'application/pdf',
  });
  await client.medCases.appeal(medCase.id, 'Order delivered; signed receipt attached.');
}

安装方法及其他语言请参见官方 SDK。

#交易 metadata 字段

被争议的收款也可能在其 metadata 中携带信息性数据块。它们仅供 参考,不具权威性:它们反映的是关于该案件所报告的内容,只读, 可能在每次案件事件时变化,且其结构可能改变。请勿基于它们构建逻辑 ——请使用上文的 med_case 对象。

#metadata.med——出现在被争议的收款上

此数据块中可能出现其他键;请忽略您无法识别的键。

#metadata.failure——出现在 expired / cancelled / failed 收款上

#相关内容

• MED webhook 载荷和签名:Webhooks。
• 自愿退款(与 MED 不同):请参见 Pix 中有关退款的问题以及 API 参考。