Webhook 通知 — API Checkout

當 Checkout 訂單狀態發生變更時，PSC 向商戶的 callbackUrl 發送 POST 請求。

Webhook 請求頭

請求頭	類型	說明	示例
X-Timestamp	Long	通知時間戳（毫秒）	1640000000000
X-Signature	String	請求簽名（Base64編碼）。算法：Base64(HMAC-SHA256(timestamp + "\n" + "POST" + "\n" + path + "\n" + Base64(SHA256(requestBody)), apiSecret))	base64-hmac-sha256

簽名驗證

1. 從請求頭中獲取 X-Timestamp 和 X-Signature
2. 讀取完整的原始請求體字符串（不能反序列化再序列化）
3. 計算：
   • bodySha256Base64 = Base64(SHA256(requestBody))
   • signContent = timestamp + "\n" + "POST" + "\n" + path + "\n" + bodySha256Base64
   • expectedSignature = Base64(HMAC-SHA256(signContent, apiSecret))
4. 將 expectedSignature 與 X-Signature 對比
5. 驗證時間戳在 5 分鐘內有效，防止重放攻擊

Webhook Body 字段

字段	類型	說明	示例
acquiringOrderId	String	平台訂單號	ORD_20240101_1234567890ABCDEF
paymentOrderId	String	支付訂單號	PAY_20240101_1234567890ABCDEF
merchantId	String	商戶號	MCH_20240101_ABC123
merchantOrderId	String	商戶訂單號	ORDER_2024010112345678
status	String	訂單狀態：PROCESSING / SUCCEEDED / FAILED / CLOSED	SUCCEEDED
finalStatus	Boolean	是否為終態	true
orderAmount	Object	訂單金額	{"value": "100.50", "currency": "USDC"}
cryptoPaymentAmount	Object	應付金額	{"value": "101.00", "currency": "USDC"}
cryptoPaidAmount	Object	實際支付金額	{"value": "101.00", "currency": "USDC"}
depositAddress	String	收款地址	TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b
network	String	區塊鏈網絡代碼	tron
networkDisplayName	String	網絡展示名稱	TRON Network
cryptoPaymentDetail	Object	鏈上交易詳情（結構同查詢訂單）	-
paymentMethodType	String	支付方式類型	ON_CHAIN_TRANSFER
paymentMethodValue	String	支付方式值（鏈上支付為 null）	null
callbackUrl	String	商戶回調地址	https://api.merchant.com/webhooks/payment

響應要求

商戶端必須在 5 秒內返回 HTTP 200 及：

{
  "code": "00000"
}

非 200 響應或超時將觸發重試。

重試策略

重試次數	距上次失敗的間隔
1	1 分鐘
2	5 分鐘
3	15 分鐘
4	30 分鐘
5	1 小時
6	2 小時
7	4 小時
8	8 小時

所有重試耗盡後，請使用 查詢 Checkout 訂單 API 手動查詢訂單狀態。

Webhook 示例

{
  "acquiringOrderId": "ORD_20240101_1234567890ABCDEF",
  "paymentOrderId": "PAY_20240101_1234567890ABCDEF",
  "merchantId": "MCH_20240101_ABC123",
  "merchantOrderId": "ORDER_2024010112345678",
  "status": "SUCCEEDED",
  "finalStatus": true,
  "orderAmount": {
    "value": "100.50",
    "currency": "USDC"
  },
  "cryptoPaymentAmount": {
    "value": "101.00",
    "currency": "USDC"
  },
  "cryptoPaidAmount": {
    "value": "101.00",
    "currency": "USDC"
  },
  "depositAddress": "TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b",
  "network": "tron",
  "networkDisplayName": "TRON Network",
  "cryptoPaymentDetail": {
    "network": "tron",
    "cryptoCurrency": "USDC",
    "transactionHash": "0x1234567890abcdef1234567890abcdef",
    "fromAddress": "TXdQKjYz8f9vN3kYh2xL6mP8sR5wT7uV2a",
    "toAddress": "TYdRLmP9kN4oY3hZ8xT6wQ2vS5uW7aV1b",
    "amount": "101.00",
    "confirmations": 21,
    "requiredConfirmations": 21
  },
  "paymentMethodType": "ON_CHAIN_TRANSFER",
  "paymentMethodValue": null,
  "callbackUrl": "https://api.merchant.com/webhooks/payment"
}

相關文檔

• API Checkout 參考文檔 — 完整接口與字段說明
• API Checkout 整合指南 — 分步整合說明
• 簽名算法 — 簽名計算詳解