Xboard 插件

KukoPay 為 Xboard 提供支付插件。用戶在 Xboard 下單後會跳轉到 KukoPay 託管收銀台付款，付款成功後 KukoPay 通過簽名 Webhook 通知 Xboard 開通訂閲。

下載後可以用 SHA-256 校驗文件完整性：

shasum -a 256 kukopay-xboard-*.zip

準備工作

• 使用支持插件管理（後台有「插件管理」菜單）的 Xboard 版本。
• Xboard 站點需要能通過公網 HTTPS 訪問。插件會把 Xboard 自己的回調地址作為 notify_url 傳給 KukoPay，只有 HTTPS 地址才會被使用。
• 一個 KukoPay 商戶賬號。沙箱測試不需要等資質審核；收真實款項需要 入駐審核 通過。

安裝與配置

金額與幣種

Xboard 內部以「分」記金額，插件把它乘以匯率後四捨五入到整數，作為 KukoPay 訂單的 amount（最小貨幣單位）。例如 Xboard 標價 ¥30.00、收款幣種 USD、匯率 0.14，買家實際支付 3000 × 0.14 = 420，即 $4.20。

匯率是固定值，插件不會自動更新。匯率變化較大時請手動調整。

插件如何工作

• 下單：插件調用 POST /v1/orders，以 Xboard 的訂單號作為 out_trade_no，並帶上 Idempotency-Key。用戶重複點擊支付不會產生兩筆訂單。
• 有效期：Xboard 會自動取消創建超過 2 小時仍未支付的訂單。插件據此設置 expires_at，讓收銀台在 Xboard 訂單創建後 1 小時 50 分關閉，比 Xboard 取消訂單早 10 分鐘。這樣買家不會在訂單被取消之後還能付款。
• 回調：插件校驗 X-KukoPay-Signature，拒絕超過 5 分鐘的時間戳，簽名密鑰輪換期間新舊密鑰都能驗簽通過。只有 payment.succeeded 且訂單狀態為 paid 時才通知 Xboard 開通訂單；其他事件只確認收到。
• 排障：下單失敗時，插件會把 KukoPay 返回的 request_id 寫進 Xboard 日誌。拿這個 request_id 到控制台「開發者 → 調用日誌」可以看到完整的請求和錯誤原因。

常見問題

付款成功了，但 Xboard 訂單沒有開通

到控制台「開發者 → Webhook」查看投遞記錄：

• 沒有投遞記錄：通知地址沒有配置，並且 Xboard 站點不是 HTTPS，所以插件沒有傳 notify_url。按上文配置通知地址。
• 對方返回 4xx / 5xx：最常見的是簽名密鑰填錯，或填了另一個環境的密鑰。用「發送測試回調」確認。
• 超時或連接失敗：檢查 Xboard 站點的防火牆、CDN 或 WAF 是否攔截了來自 KukoPay 的 POST 請求。

修好後可以在投遞記錄裏手動重投，不需要讓用戶重新付款。

下單時報「該商戶訂單號已有訂單」

同一個 Xboard 訂單第二次發起支付時，金額、幣種、標題或地址與第一次不同，最常見的原因是中途改了匯率或貨幣單位。讓用戶取消這筆訂單重新下單即可。

提示「訂單即將超時，請取消後重新下單」，或收銀台提示鏈接已過期

收銀台在 Xboard 訂單創建 1 小時 50 分後關閉（見上文「有效期」）。離關閉不到 5 分鐘時，插件不再發起支付。讓用戶取消這筆訂單、重新下單即可。

正式環境下單被拒絕

常見原因：賬戶尚未通過入駐審核；貨幣單位不是平台為你開通的幣種；Xboard 站點不是 HTTPS 且控制台沒有配置正式環境的通知地址。具體原因看 Xboard 日誌裏的錯誤信息，或拿 request_id 到調用日誌查詢。

升級插件

下載新版本 zip，在「插件管理」中再次上傳即可，Xboard 會按版本號覆蓋升級，已填寫的支付配置保持不變。