GET /v1/disputes
GET /v1/disputes/{dispute_no}拒付的概念、資金流向和應對流程見 拒付與爭議。這裏只講接口。
列表
除 通用列表參數 外：
| 參數 | 説明 |
|---|---|
status | needs_response / under_review / won / lost / closed |
trade_no | 只看某一筆訂單的拒付 |
最該定期跑的一條查詢是"還需要我舉證的案件"：
curl -G "https://api.kukopay.com/v1/disputes" \
-H "X-Api-Key: kuko_live_你的密鑰" \
-d status=needs_response單個拒付
{dispute_no} 既接受平台拒付號，也接受上游渠道的拒付號——和收單機構後台核對時通常手上只有後者。
curl "https://api.kukopay.com/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 /v1/disputes/{dispute_no}/evidence
POST /v1/disputes/{dispute_no}/evidence不舉證等於敗訴。 超過 evidence_due_by 未響應，結果與主動認輸完全相同。
curl -X POST "https://api.kukopay.com/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://web.kukopay.com/api/files/kukopay/merchant-onboarding/…/dispute_evidence/1757000000000_ab12.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://web.kukopay.com/api/files/…），且必須是本賬戶成員上傳的文件，否則返回 400 invalid_request。平台直接從自己的私有存儲讀取文件，不會去請求你給的 URL；文件本身不公開，只有登錄後的本賬戶成員和平台審核人員能打開。
分多次組裝
# 先存草稿
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 /v1/disputes/{dispute_no}/acceptcurl -X POST "https://api.kukopay.com/v1/disputes/dsp_4a7c1e9b/accept" \
-H "X-Api-Key: kuko_live_你的密鑰"資金結果與放任舉證期過期相同，區別是立刻結案而不是等到截止日。
狀態不會立即變成 lost。它跟隨通道自己的確認，因為那才是真正扣賬的時點——結案時會推送 dispute.lost，爭議金額從凍結中扣除，並收取拒付處理費。