商戶 API 概覽

概述

HissPay 提供代收（向付款人收款）與代付（向收款帳戶付款）介面，均為 HTTPS POST + JSON。正式環境閘道：https://transaction.hisspay.com；沙箱閘道：https://sandbox-api.hisspay.com。

產品目錄中的幣種：AUD, EUR, GBP, INR, JPY, THB, USD, USDT。出現在目錄中不等於已為您開通；您的產品編碼、金額範圍與費率以開通通知為準。

接入準備

接入前請確認：商戶已審核啟用；已在商戶後台（mch.hisspay.com →「應用金鑰」）建立 API 應用並取得 appId 與 appSecret；已簽約代收、代付產品；代付已設定伺服器公網出口 IP 白名單；已準備公網 HTTPS 通知地址。建議先在沙箱完整聯調。

簽章規則

每個請求都帶 appId、timestamp（毫秒，與平台時間差不超過 30 秒）、nonce（至少 10 個字元，不可重複）與 sign 請求頭。sign 為請求體欄位加上 appId、timestamp、nonce，按欄位名升序拼成 key=value 並以 & 連接，末尾直接接 appSecret 後計算的 SHA-256 小寫十六進位。不是 HMAC；不要傳 null，也不要把 appSecret 放在網頁或 App 中。

代收下單

POST /transaction/payin/v1/apply 建立代收訂單並返回付款連結 payUrl。付款結果只以驗簽通過的通知或查單為準，不以瀏覽器跳轉為準。

代付下單

POST /transaction/payout/v1/apply 為非同步處理：code=0 只表示已受理、不代表已到帳。逾時或返回 500 表示結果未確認：請先查詢原單，並按完整文件的處理規則判斷後再決定是否重新提交。

USDT 收款

USDT 代收使用 currency=USDT 及平台分配的各網路產品編碼，金額最多 4 位小數；結果以通知或查單確認。

泰國（THB）

泰國（THB）：PromptPay 掃碼代收與泰國銀行轉帳代付。代收銀行編碼：SCB, KBANK, KTB, BAY, GSB, TTB；代付銀行編碼：SCB, KBANK, KTB, BAY, GSB, TTB, BBL（您可用的銀行以開通通知為準）。單筆預設範圍：500.00–49999.00 THB。

訂單查詢

POST /transaction/payin/v1/query 與 POST /transaction/payout/v1/query 以 merchantOrderNo 或 orderNo 查詢；每個 appId 每秒最多 5 次，建議輪詢間隔 3–5 秒並退避。

餘額查詢

POST /transaction/payout/v1/balance 返回指定幣種的 balance（帳面）、balanceActive（可用）與 balanceFreeze（凍結）。

非同步通知

平台以 POST JSON 通知您的 notifyUrl，並帶同樣的四個簽章請求頭。請先驗簽、按訂單冪等處理，再回覆 SUCCESS 或 OK（精確匹配）。未確認的通知會有限次數重試。

訂單狀態

訂單狀態請結合 payStatus、paymentStatus 與 isFinal 判斷；代收查單 payStatus=0 不代表付款失敗。

錯誤碼

code=0 表示介面呼叫成功，付款結果另看訂單狀態。各錯誤碼及建議處理見完整文件。

完整範例

建立沙箱商戶，依沙箱測試指南執行 quickstart 套件與 5 分鐘自檢，再按上線清單切換正式環境。