跳轉到主要內容

Xboard 支付插件:如何讓 Xboard 接收銀行卡和錢包付款

KukoPay Xboard 支付插件設置教程:安裝插件、填入 API 密鑰和簽名密鑰、設置幣種與匯率、在沙箱測試,以及常見問題排查。

發佈於 約 4 分鐘閲讀

手繪插畫:一個 Xboard 插件配置框,填有 API 密鑰和簽名密鑰,連到收銀台,再以簽名通知返回,旁邊一個人朝它走來
本文目錄
  1. 用插件,還是 Xboard 自帶的 EPay?
  2. 準備工作
  3. 如何設置 Xboard 支付插件
  4. 幣種與匯率
  5. 插件在背後做了什麼
  6. Xboard 支付插件常見問題排查
  7. 總結

Xboard 支付插件把 Xboard 面板接入 KukoPay,用戶可以在託管收銀台上用銀行卡或錢包購買套餐,付款後訂閲自動開通。你只需要上傳插件、填入 API 密鑰和簽名密鑰、把它添加為支付方式——不用寫代碼。用戶付款後,KukoPay 會向 Xboard 發送一條簽名通知,Xboard 據此把訂單標記為已支付。

這篇文章一步步介紹 Xboard 支付插件的設置、金額與幣種如何換算、如何在沙箱測試、插件在背後做了什麼,以及最常見問題的排查方法。

用插件,還是 Xboard 自帶的 EPay?

Xboard 有兩種方式接入 KukoPay:

KukoPay 插件自帶的 EPay
安裝上傳一個插件什麼都不用裝
協議KukoPay 原生 API,HMAC 簽名的 Webhook易支付協議,MD5 簽名
憑據API 密鑰 + Webhook 簽名密鑰商戶 ID(pid)+ 密鑰

兩種都能用。插件走原生 API,簽名更安全;EPay 不用安裝任何東西,見 易支付接入指南。

準備工作

  • 支持插件管理的 Xboard 版本(後台有「插件管理」菜單)。
  • Xboard 站點可以通過公網 HTTPS 訪問——只有 HTTPS 地址,插件才會把 Xboard 的通知地址傳給 KukoPay。
  • 一個 KukoPay 賬戶。沙箱不需要審核;正式收款需要通過 資質審核。

如何設置 Xboard 支付插件

上傳並啓用插件

從 Xboard 插件頁面 下載插件(每個版本都附有 SHA-256 校驗值,可以核對),然後在 Xboard 的「插件管理」中上傳 zip,安裝並啓用 KukoPay。

從 KukoPay 控制台取兩個值

切換到用來接 Xboard 的應用(單獨建一個應用,可以讓它的訂單、密鑰和通知與你的其他業務分開,見 多個網站如何接入收款)。在 開發者 → API 密鑰 頁面簽發一把 API 密鑰,以及應用的回調簽名密鑰。先用沙箱的值:kuko_test_ 開頭的密鑰和沙箱簽名密鑰。

在 Xboard 添加支付方式

在 Xboard 的支付配置中添加一個支付方式,接口選 KukoPay,填入 API 密鑰、簽名密鑰、貨幣單位(USD、HKD 或 CNY)、匯率和收銀台語言(zh 或 en)。保存後記下這個支付方式的通知地址。

發送測試回調

在 開發者 → 沙箱聯調 中選中這個應用,向該通知地址發送一條測試回調。返回 2xx 就説明地址和簽名密鑰都對了;插件會直接確認收到,不會開通任何訂單。

在沙箱跑通一筆

在 Xboard 前台下一個訂單,在收銀台用測試卡 4242 4242 4242 4242 付款,有效期填任意未來日期,安全碼填任意 3 位數字。Xboard 訂單應該變為已支付,訂閲隨之開通。

切換到正式環境

審核通過後,把 API 密鑰和簽名密鑰換成同一個應用在正式環境的值。兩者必須來自同一個環境。

幣種與匯率

Xboard 以「分」記金額。插件把金額乘以你填的匯率,四捨五入到最小貨幣單位的整數:Xboard 標價 ¥30.00、貨幣單位 USD、匯率 0.14 時,實際收取 3000 × 0.14 = 420,即 $4.20。如果 Xboard 的標價幣種與收款幣種相同,匯率填 1。

匯率是固定值,插件不會自動更新。匯率變化較大時請自己調整;另外,正式環境只能使用你賬戶已開通的幣種。見 如何在網上接收美元付款 和 跨境收款手續費怎麼算。

插件在背後做了什麼

  • 下單時以 Xboard 的訂單號作為 out_trade_no,並帶上 Idempotency-Key,用戶重複點擊支付不會產生兩張訂單。
  • 在 Xboard 取消訂單之前關閉收銀台。 Xboard 會取消創建超過 2 小時仍未支付的訂單;插件把收銀台設為在 Xboard 訂單創建後 1 小時 50 分關閉,這樣沒有人能為一張即將被取消的訂單付款。見 如何取消未支付訂單。
  • 校驗每一條通知——簽名、不超過 5 分鐘的時間戳,以及輪換期間新舊兩個密鑰——只有在 payment.succeeded 且訂單為 paid 時才開通訂單。
  • 記錄 request_id:下單失敗時,插件把它寫進 Xboard 日誌,你可以在 開發者 → API 日誌 找到完整的請求。

Xboard 支付插件常見問題排查

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

打開 開發者 → Webhook 中的投遞記錄:

  • 沒有投遞記錄——站點不是 HTTPS,所以沒有傳通知地址。為這個應用添加一個 Webhook 端點,地址填通知地址,並把這個端點的簽名密鑰填進插件。
  • 返回 4xx / 5xx——通常是簽名密鑰填錯,或填了另一個環境的密鑰。用測試回調確認。
  • 超時——Xboard 前面的防火牆、CDN 或 WAF 攔截了 POST 請求。

修好後在投遞記錄裏重新投遞即可,用戶不需要再付一次。

提示「該商戶訂單號已有訂單」

同一張 Xboard 訂單第二次發起支付時,金額或幣種與第一次不同——通常是中途改了匯率或貨幣單位。讓用戶取消這張訂單,重新下單。

收銀台提示鏈接已過期

收銀台在 Xboard 訂單創建 1 小時 50 分後關閉,最後 5 分鐘內插件不再發起支付。取消後重新下單即可。

正式環境下單被拒絕

賬戶還沒通過審核、幣種沒有為正式環境開通,或者站點不是 HTTPS 且沒有配置正式環境的通知地址。Xboard 日誌裏的錯誤信息,或 API 日誌裏的 request_id,會告訴你是哪一種。

總結

  • Xboard 支付插件把 KukoPay 添加為支付方式:上傳插件,填入 API 密鑰和簽名密鑰,設置幣種、匯率和語言;
  • 匯率把 Xboard 的標價換算成收款幣種,不會自動更新;
  • 用測試回調和 4242 沙箱付款測試,然後把兩個憑據都換成同一個應用的正式環境值;
  • 插件下單冪等,在 Xboard 取消訂單前 10 分鐘關閉收銀台,並校驗每一條通知;
  • 大多數問題是缺少 HTTPS 通知地址、密鑰不匹配,或改了匯率。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。