商戶服務端 KukoPay 買家瀏覽器
│ POST /orders │ │
│─────────────────────▶│ │
│ checkout_url │ │
│◀─────────────────────│ │
│ 重定向買家到 checkout_url │
│───────────────────────────────────────────────▶│
│ │◀──── 輸入支付信息 ───────│
│ │ │
│ payment.succeeded │ │
│◀─────────────────────│──── 回跳 return_url ───▶│return_url 只負責買家體驗，不是支付憑據。買家可能關掉頁面或回跳可能被偽造。請以驗簽後的 payment.succeeded Webhook 作為履約依據。
訂單狀態
| 狀態 | 含義 |
|---|---|
pending | 已創建，等待買家付款 |
paid | 支付成功，淨額已記入商戶錢包 |
partially_refunded | 已發生部分退款 |
refunded | 已全額退款 |
failed | 渠道明確返回失敗或取消 |
expired | 收銀台鏈接過期（訂單的 expires_at，默認創建後 24 小時）仍未支付，由對賬任務關閉 |
後台對賬任務會核對未決支付與退款。即使渠道通知暫時丟失、買家又關閉了頁面，平台仍會重新讀取渠道結果並補入賬、補通知或關閉訂單。
更換支付方式與重複付款
買家可以在收銀台更換當前訂單和地區實際可用的支付方式。checkout_url 在有效期（默認 24 小時）內都可以回來繼續付款。
為保證一筆訂單只收一次錢，平台在切換前會先取消買家尚未完成的那筆支付，確認取消成功後才發起新的支付。如果取消時發現買家恰好已經付款，平台直接按這筆付款入賬，不會再讓買家付第二次。
因此一張訂單在付款過程中可能先後對應多筆渠道支付，訂單對象的 payment_id 會隨之變化。請以 trade_no / out_trade_no 和 payment.succeeded 事件對賬，不要把 payment_id 當作訂單的唯一標識。
極少數情況下，買家的付款會在訂單已經關閉之後才到達，例如訂單已由另一筆付款支付，或已超時關閉。平台對這類付款的處理規則是：
| 到達時訂單的狀態 | 平台的處理 |
|---|---|
pending（尚未支付） | 按這筆付款正常入賬，發送 payment.succeeded |
其他任何狀態（paid、partially_refunded、refunded、expired、failed） | 全額原路退回買家，發送 payment.duplicate_refunded |
退回的錢從未計入商戶錢包，所以不會影響商戶餘額，也不會產生手續費或退款流水。payment.duplicate_refunded 只是通知，商戶無需任何操作。同一訂單多次發生這種情況時，只會發送一次該事件。
資金入賬
支付確認時，平台在同一結算事務內更新訂單、計算手續費、增加錢包賬面可用餘額並寫入對應賬本流水。正式提現還要等待上游資金可用並完成對賬。金額在 API 與賬本中始終使用最小貨幣單位。