买家发起 Chargeback 时资金如何变化，以及你需要做什么。
买家可以绕过你，直接向发卡行主张这笔交易有问题。这叫拒付（Chargeback），一旦发起，资金就已经被上游扣留——它是既成事实，不是一个可以拒绝的请求。
拒付开案的那一刻，争议金额会从可用余额移到冻结余额：
开案 available -= amount, frozen += amount dispute_freeze
胜诉 frozen -= amount, available += amount dispute_unfreeze
败诉 frozen -= amount dispute_debit
available -= 处理费 dispute_fee冻结不做余额充足性检查，可用余额可以变成负数。如果你在拒付发起前已经把这笔钱提走了，负余额就是你欠平台的金额，它会一直挡住后续提现，直到被后续收款补平。
败诉时除了扣回争议金额，还会收取一笔拒付处理费（默认 $15.00，按商户可配）。这笔费用覆盖上游收单机构的争议处理成本，胜诉不收。
| 状态 | 含义 | 资金 |
|---|---|---|
needs_response | 已开案，等待举证 | 冻结中 |
under_review | 已提交申诉，发卡行审理中 | 冻结中 |
won | 申诉成功 | 已解冻退回 |
lost | 申诉失败 / 未按时举证 / 主动接受 | 已扣账 + 处理费 |
closed | 发卡行撤销了拒付 | 已解冻退回 |
不举证等于败诉。 超过 evidence_due_by 未响应会直接进入 lost，和主动认输的结果完全一样。
在 Webhook 端点上订阅 dispute.created，这是你唯一能第一时间知道被拒付的渠道。没有订阅就只能靠轮询 拒付列表。
事件里的 data.object.trade_no 指向原订单。拿它查出发货记录、物流凭证、买家沟通记录。
调用 提交证据 把材料发给发卡行。哪些字段有用取决于拒付原因，见下表。
curl -X POST "https://web.kukopay.com/api/v1/disputes/dsp_xxx/evidence" \
-H "X-Api-Key: kuko_live_你的密钥" \
-H "Content-Type: application/json" \
-d '{
"evidence": {
"shipping_carrier": "DHL",
"shipping_tracking_number": "JD0099887766",
"shipping_date": "2026-09-02",
"product_description": "Pro 年度订阅"
},
"submit": true
}'结案时会推送 dispute.won / dispute.lost / dispute.closed，资金同步变化。
发卡行只看与争议点相关的材料，堆砌无关文件不会提高胜率。
| 拒付原因 | 最该提供的 |
|---|---|
| 未收到货 | shipping_carrier · shipping_tracking_number · shipping_date · shipping_documentation 文件 |
| 商品与描述不符 | product_description · receipt 文件 · customer_communication 文件 |
| 订阅已取消 | cancellation_rebuttal · cancellation_policy_disclosure · cancellation_policy 文件 |
| 要求退款被拒 | refund_policy_disclosure · refund_refusal_explanation · refund_policy 文件 |
| 未授权 / 盗刷 | customer_purchase_ip · customer_email_address · billing_address · customer_signature 文件 · access_activity_log |
| 重复扣款 | invoice_showing_distinct_transactions 文件 |
submit: false 可以先暂存草稿、分多次补充材料；submit: true 才会真正发给发卡行，且不可撤回。提交后拒付进入 under_review，冻结金额不变。
调用 接受拒付 直接认输。
资金结果与放任举证期过期完全一样，区别是立刻结案，而不是让争议金额一直冻结到截止日。如果你已经确认是自己的责任，早点认输能更快把剩余资金解放出来。
订单存在未结案拒付时，退款接口返回 409 conflict。
原因很直接：上游已经把这笔钱扣留了，再退一次等于把同一笔钱付给买家两次。想认输的话，让拒付走到 lost 即可，不要用退款去"处理"拒付。
拒付在资金流水里表现为四种类型，都可以用 资金流水接口 按 type 筛选：
dispute_freeze · dispute_unfreeze · dispute_debit · dispute_fee
每一行的 reference_id 都是 dispute_no，可以直接和拒付记录对上。
即使 Webhook 全部漏掉，平台的对账巡检也会定期从上游重新拉取未结案拒付并推进状态，所以不会出现资金被永久冻结的情况。