V2Board 支付網關:用自帶的 EPay 接收銀行卡和錢包付款
如何用 V2Board 自帶的 EPay 支付方式設置支付網關:網關地址、商戶 ID 和密鑰、訂單有效期怎麼設、如何測試以及常見問題排查。
V2Board 支付網關,就是 V2Board 在用戶購買套餐時把用戶交給的那個付款渠道。V2Board 本身就帶有一個使用易支付(epay)協議的 EPay 支付方式,而 KukoPay 提供兼容易支付協議的網關——所以只要填三個值,V2Board 就能接收銀行卡和錢包付款,不用安裝插件,也不用改代碼。每一筆付款都會成為一張普通的 KukoPay 訂單,在託管收銀台上支付,成功後再通知回 V2Board。
這篇文章介紹如何用 KukoPay 設置 V2Board 支付網關:開通易支付、要填哪些字段、訂單有效期怎麼選、如何在沙箱測試,以及常見問題的排查。同樣的步驟也適用於 SSPanel 和獨角數卡。
準備工作
- 一個後台可以使用 EPay 支付方式的 V2Board 站點。
- 一個 KukoPay 賬戶。沙箱不需要審核;正式收款需要通過 資質審核。
- 最好為面板單獨建一個 KukoPay 應用,讓它的訂單、憑據和通知與你的其他業務分開,見 多個網站如何接入收款。
如何設置 V2Board 支付網關
在 KukoPay 開通易支付
在控制台切換到用於 V2Board 的應用,打開 開發者 → 易支付接入 並開通。你會得到網關地址(https://api.kukopay.com/epay)、純數字的商戶 ID(pid)和 32 位的商戶密鑰,以及兩個設置:收款幣種和訂單有效期。沙箱和正式環境各有自己的 pid 和密鑰。
選擇幣種
易支付的 money 字段只有數字、沒有幣種,所以訂單按這裏選擇的幣種收款(USD、HKD 或 CNY;正式環境只能選賬戶已開通的)。請選擇 V2Board 標價所用的幣種。
把訂單有效期設得比 V2Board 短
V2Board 會在 2 小時後取消未支付的訂單。把 KukoPay 的訂單有效期設得比這更短(可選 5 分鐘到 24 小時,默認 30 分鐘),讓收銀台在 V2Board 取消訂單之前關閉。下文會詳細説明原因。
在 V2Board 添加 EPay 支付方式
在 V2Board 的支付設置中,添加一個使用 EPay 的支付方式,填入網關地址、商戶 ID 和密鑰。支付類型可以留空——收銀台會顯示你賬戶已開通的所有支付方式,由買家選擇。
在沙箱跑通一筆
用沙箱的 pid 和密鑰在 V2Board 下一個訂單,用測試卡 4242 4242 4242 4242 付款。V2Board 訂單應該變為已支付。見 支付測試卡號大全。
切換到正式環境
審核通過後,把商戶 ID 和密鑰換成正式環境的。環境只由 pid 決定。
為什麼訂單有效期很重要
易支付協議沒有表示訂單何時失效的字段,而 V2Board 會按自己的時間取消未支付的訂單。如果 KukoPay 的收銀台開得比這更久,買家就可能為一張 V2Board 已經取消的訂單付款——通知到了,卻沒有訂單可以開通。讓 KukoPay 的有效期更短,最壞的情況只是買家重新下單,而不會出現一筆無處可去的付款。
其他系統也要做同樣的檢查:獨角數卡默認是 5 分鐘,所以為它把 KukoPay 的有效期設為 5 分鐘。SSPanel 請查一下它的訂單超時時間,並設得比它短。修改只對之後創建的訂單生效。背後的原理見 易支付接入指南。
V2Board 會在什麼時候收到什麼
- 只通知支付成功。 KukoPay 向 V2Board 發送一個帶簽名、
trade_status=TRADE_SUCCESS的 GET 請求,並期待返回內容為success。失敗和過期從不通知,因為很多易支付客戶端只校驗簽名、不看狀態,會把任何通知都當成已支付。 - 重試。 10 秒內沒有收到
success,會在 30 秒、2 分鐘、10 分鐘、30 分鐘和 2 小時後重試——總共最多 6 次。 - 返回。 買家付款後回到 V2Board 的返回頁,帶着同樣的簽名參數;V2Board 根據通知而不是返回頁來開通訂單。
- 其他一切——退款、拒付、提現——都在 KukoPay 控制台處理,V2Board 不需要支持。
V2Board 支付常見問題排查
下單時提示「簽名校驗失敗」
密鑰填錯了,或者 pid 和密鑰來自不同的環境。重置密鑰立即生效、沒有過渡期——重置後請馬上更新 V2Board。
付款成功了,但 V2Board 沒有開通訂單
打開 開發者 → Webhook 中的投遞記錄:
- V2Board 返回的不是
success——它的處理代碼出錯或驗簽失敗,返回內容會説明原因。 - 超時或連接錯誤——V2Board 前面的防火牆、CDN 或 WAF 攔截了請求。
修好後在投遞記錄裏重新投遞即可,買家不需要再付一次。
提示「商戶尚未通過資質審核」
你在資質審核通過前用了正式環境的 pid。在那之前請使用沙箱憑據。
用插件、EPay 還是 API?
對 V2Board 來説,EPay 是最簡單的方式。Xboard(V2Board 的一個分支)另有一個基於原生 API、使用 HMAC 簽名 Webhook 的 KukoPay 專用插件,見 Xboard 支付插件。如果是你自己寫的系統,直接對接 API 更好,見 支付網關接入。
總結
- V2Board 自帶的 EPay 支付方式用三個值接入 KukoPay 的易支付兼容網關:網關地址、商戶 ID(
pid)和密鑰; pid決定環境和應用;收款幣種在控制台選擇;- 把 KukoPay 的訂單有效期設得比 V2Board 的 2 小時取消時間短(獨角數卡設 5 分鐘);
- 只通知支付成功,帶簽名,在 V2Board 返回
success之前最多重試 6 次; - 大多數問題是密鑰或環境不匹配,或者防火牆攔截了通知。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。