🔔 Webhook 通知

設定 Webhook 以接收通知。HaloPay 會將最終交易結果通知商戶。可在 應用管理頁面 設定 Webhook URL。

當發生以下事件時，會向商戶設定的回呼介面發起請求：

✅ 支付交易成功
⏱️ 支付逾時
💡 支付不足
✅ 出款成功
❌ 出款失敗

回呼頻率：5s、15s、30s、3m、10m、20m、30m、30m、30m、60m、3h、3h、3h、6h、6h。總計：24h3m50s

回呼內容仍然經過加密處理。詳情請參閱簽章。

Webhook 通知

請求標頭

名稱	值	必填	類型	說明
X-Appid	h3j6k9m2n...	Y	string	商戶唯一憑證。在應用管理頁面查看。
X-Timestamp	1700349280	Y	string	秒級時間戳（10 位）。請求有效期為 2 分鐘。
X-Sign	e0c6a719ebc366da...	Y	string	hmacSHA256(body（json 字串）+timestamp+appKey)
X-EventType	Paid	Y	string	交易狀態碼

支付 Body

{
  "appid": "ad4cyr8dpfs...",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd...",
  "status": "PAID",  (TO-BE-PAID/PAID/TIME-OUT)
  "time": 1773471015
}

💡

即使客戶未支付全額，我們仍會傳送狀態欄位設為 TO-BE-PAID 的回呼通知，而 amount_collected 欄位將顯示已支付的代幣數量。

若超過支付時間上限，我們將傳送狀態欄位設為 TIME-OUT 的回呼，而 amount_collected 欄位將再次顯示已支付的代幣數量。

出款 Body

{
  "appid": "ad4cyr8dpfs...",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "currency_id": 75,
  "status": "PAID",  (PAID/FAIL)
  "time": 1773473637,
  "token_amount": "1",
  "trade_no": "202603141533083d1eba01c48c2a873c",
  "txid": "aa23e0aebd2e4c5b82786a5e8b1f414222c7c5...",
  "type": "TRANSFER"
}

QR 支付 Body

{
  "appid": "1aiqfs0agr...", (預設與支付 APPID 不同。)
  "trade_no": "2c8b150bf35abc59189e333c107247db",
  "type": "QR_PAYMENT",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TRX",
  "txid": "2cdf12e85ec73a61280daaf49c4f27686519407f...",
  "currency_id": 75,
  "from_address": "TSpjU4PUYzAyY88wyKEEMD7MryneC1WL...",
  "to_address": "TY1RJdyJh4y1tgmPFrnSaWFhM1HwqTvC...",
  "token_amount": "11",
  "status": "PAID",  (PAID)
  "time": 1773473913
}

參數說明

欄位	類型	說明
appid	string	商戶 APPID
trade_no	string	交易 ID
out_trade_no	string	商戶訂單 ID
amount	string	交易金額（法定貨幣金額）
token_amount	string	交易金額（代幣）
chain	string	鏈名稱
chain_id	int	鏈 ID
type	string	交易類型（「PAYMENT/TRANSFER/QR_PAYMENT」）
currency_id	int	全域唯一貨幣 ID TokenList
txid	string	鏈上交易雜湊
status	string	交易狀態（TO-BE-PAID/PAID/TIME-OUT/FAIL）。訂單未完全支付時會觸發 TO-BE-PAID 回呼。
time	int	最終鏈上時間（若失敗則傳回逾時期間）
amount_collected	string	使用者已支付的代幣數量
contract	string	代幣的合約位址，主要貨幣為 ETH/TRX/BNB
from_address	string	支付錢包位址
to_address	string	接收錢包位址

💡

商戶需驗章以保證安全。處理成功後請在 HTTP 回應體中回傳 "Success"。若處理失敗，HaloPay 會重試推送，Webhook 最多重試約 15 次（回呼頻率：5s、15s、30s、3m、10m、20m、30m、30m、30m、60m、3h、3h、3h、6h、6h，總計約 24h3m50s）。

📌 範例

對商戶 Webhook 伺服器的請求

POST /webhook/callback HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Appid: ad4cyr8dpfs...
X-Timestamp: 1773471015
X-Sign: e0c6a719ebc366da...
X-EventType: Paid

{
  "appid": "ad4cyr8dpfs...",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd...",
  "status": "PAID",
  "time": 1773471015
}

商戶 Webhook 伺服器的回應

HTTP/1.1 200 OK
Content-Type: text/plain

Success

Webhook 通知​

📌 範例​

Webhook 通知

📌 範例