創建退款
POST https://api.kukopay.com/v1/refunds
curl -X POST "https://api.kukopay.com/v1/refunds" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $KUKOPAY_API_KEY" \
-d '{
"trade_no": "TRD_9F3A...",
"out_refund_no": "REF_20260921_0001",
"amount": 1000,
"reason": "買家協商退貨"
}'| 字段 | 必填 | 説明 |
|---|---|---|
trade_no | 是 | 原訂單的 KukoPay 交易號 |
out_refund_no | 正式必填 | 商戶退款單號，也是退款冪等鍵 |
amount | 否 | 退款金額，單位分，必須為正整數；省略表示退剩餘全部金額 |
reason | 否 | 退款原因 |
同步完成時狀態為 succeeded。部分渠道異步處理退款，此時返回 HTTP 202 和 pending：金額先從可用餘額轉入凍結，渠道確認成功後正式扣除併發送 refund.succeeded；若渠道拒絕，凍結金額會退回可用餘額。
查詢退款
GET https://api.kukopay.com/v1/refunds/{refund_no}
路徑參數接受平台 refund_no 或商戶 out_refund_no。
curl "https://api.kukopay.com/v1/refunds/REF_20260921_0001" \
-H "X-Api-Key: $KUKOPAY_API_KEY"關鍵字段：
| 字段 | 含義 |
|---|---|
status | pending / succeeded / failed |
funds_frozen | 是否仍有金額被該退款佔用 |
settled_at | 完成扣賬的時間，處理中為 null |
建議收到 pending 後每 10 秒查詢一次，最多持續 5 分鐘，之後改為低頻兜底查詢。後台對賬任務也會持續核對未決退款。
退款期限
部分支付方式只能在一段時間內退款，例如支付寶、微信支付。訂單對象的 refundable_until 給出最晚可退款時間，沒有期限時為 null。超過期限的退款請求會被直接拒絕，返回 HTTP 400 和 refund_window_expired，不會扣減餘額，也不會發送給支付通道。這類訂單請與買家線下協商處理。
同一個 out_refund_no 在期限內已被受理的，期限過後重複請求仍會返回原退款結果。
退款需要足夠的可用餘額。支持多次部分退款，但累計金額不能超過原訂單金額；手續費不隨退款退回。