拒付 | KukoPay

开发者文档

拒付

查询买家发起的 Chargeback 及其资金状态。

GET /api/v1/disputes
GET /api/v1/disputes/{dispute_no}

拒付的概念、资金流向和应对流程见拒付与争议。这里只讲接口。

列表

除通用列表参数外：

参数	说明
`status`	`needs_response` / `under_review` / `won` / `lost` / `closed`
`trade_no`	只看某一笔订单的拒付

最该定期跑的一条查询是"还需要我举证的案件"：

curl -G "https://web.kukopay.com/api/v1/disputes" \
  -H "X-Api-Key: kuko_live_你的密钥" \
  -d status=needs_response

单个拒付

{dispute_no} 既接受平台拒付号，也接受上游渠道的拒付号——和收单机构后台核对时通常手上只有后者。

curl "https://web.kukopay.com/api/v1/disputes/dsp_4a7c1e9b2f6d08351ac7de" \
  -H "X-Api-Key: kuko_live_你的密钥"

响应

{
  "object": "dispute",
  "dispute_no": "dsp_4a7c1e9b2f6d08351ac7de",
  "trade_no": "TRD_9F3A2C7E...",
  "merchant_id": "mch_a1b2c3d4e5",
  "processor_dispute_id": "dp_1Nc8xyz...",
  "amount": 2990,
  "fee": 0,
  "currency": "USD",
  "status": "needs_response",
  "processor_status": "dispute_opened",
  "reason": "product_not_received",
  "mode": "live",
  "funds_frozen": true,
  "evidence_due_by": "2026-10-05T23:59:59.000Z",
  "opened_at": "2026-09-21T09:02:41.000Z",
  "closed_at": null,
  "created_at": "2026-09-21T09:02:43.117Z",
  "updated_at": "2026-09-21T09:02:43.117Z"
}

字段	说明
`amount`	争议金额，开案时已从可用余额转入冻结
`fee`	拒付处理费，败诉后才有值
`funds_frozen`	争议金额是否仍在冻结中
`evidence_due_by`	举证截止时间，过期未响应等于败诉
`processor_status`	上游渠道的原始状态，供排障与对账核对

⚠️

订单存在未结案拒付时，退款接口返回 409 conflict。上游已经扣留了这笔钱，再退一次等于付两次。

提交证据（申诉）

GET  /api/v1/disputes/{dispute_no}/evidence
POST /api/v1/disputes/{dispute_no}/evidence

🚨

不举证等于败诉。 超过 evidence_due_by 未响应，结果与主动认输完全相同。

curl -X POST "https://web.kukopay.com/api/v1/disputes/dsp_4a7c1e9b/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 年度订阅"
    },
    "files": [
      { "type": "shipping_documentation", "url": "https://files.kukopay.com/mch_xxx/proof.pdf" }
    ],
    "submit": true
  }'

参数	说明
`evidence`	文字材料，见下表。单字段不超过 5000 字符
`files`	证据文件，最多 8 个，单个不超过 10MB
`submit`	`false`（默认）只暂存草稿；`true` 才发给发卡行，不可撤回

文字字段

product_description · customer_name · customer_email_address · customer_purchase_ip · billing_address · shipping_address · shipping_carrier · shipping_tracking_number · shipping_date · service_date · access_activity_log · refund_policy_disclosure · refund_refusal_explanation · cancellation_policy_disclosure · cancellation_rebuttal

哪些字段有用取决于拒付原因，对照表见拒付与争议。

文件类型

receipt · customer_communication · customer_signature · shipping_documentation · service_documentation · cancellation_policy · refund_policy · invoice_showing_distinct_transactions · recurring_transaction_agreement · uncategorized_file

⚠️

files[].url 必须是平台存储域名下的 HTTPS 地址——先通过商户后台上传，再引用返回的地址。平台会拒绝其它任何域名，这是为了防止接口被用来探测内网。

分多次组装

# 先存草稿
curl ... -d '{ "evidence": { "shipping_carrier": "DHL" }, "submit": false }'
 
# 补充运单号后一起提交
curl ... -d '{
  "evidence": { "shipping_carrier": "DHL", "shipping_tracking_number": "JD0099" },
  "submit": true
}'

每次提交都是整体替换，不是增量合并——草稿里已有的字段要一并带上。

提交成功后拒付进入 under_review，并推送 dispute.updated 事件。冻结金额不变。

接受拒付（认输）

POST /api/v1/disputes/{dispute_no}/accept

curl -X POST "https://web.kukopay.com/api/v1/disputes/dsp_4a7c1e9b/accept" \
  -H "X-Api-Key: kuko_live_你的密钥"

资金结果与放任举证期过期相同，区别是立刻结案而不是等到截止日。

ℹ️

状态不会立即变成 lost。它跟随通道自己的确认，因为那才是真正扣账的时点——结案时会推送 dispute.lost，争议金额从冻结中扣除，并收取拒付处理费。

申请退款收款链接