跳轉到主要內容
本頁說明 QFPay 在訂閱支付流程中所發送的非同步通知（Webhook）。
主要涵蓋以下三類事件：
  • payment_token：支付令牌建立
  • subscription：訂閱狀態變更
  • subscription_payment：定期扣款結果

​
如何設定 Webhook URL

若需設定或修改 Webhook 接收端點，請將以下資訊提供給 QFPay 技術支援：
  • Webhook URL
  • 商戶 ID
  • 門店 ID

​
1️⃣ 支付令牌建立通知（Token Creation Notification）

當透過 Payment Element 成功建立支付令牌後，系統會發送此通知。

​
通知類型

notify_type = payment_token

​
通知欄位說明

欄位名稱說明
useridQFPay 門店 ID
notify_type固定為 payment_token
event令牌事件類型：NEW、MATCH、CONFLICT
tokenid建立完成的支付令牌 ID
token_expiry_date令牌到期時間
cardcd遮罩後的卡號
card_scheme卡組織（例如 VISA、MASTERCARD）
respcd回應碼（0000 表示成功）
respmsg回應訊息
sysdtm系統時間
customer_id若有關聯則回傳
token_reason令牌化原因
token_reference系統內部令牌參考值

​
範例

Token Webhook Example
{
  "respmsg": "success",
  "card_scheme": "ECMC_DEBIT",
  "cardcd": "5200****1096",
  "tokenid": "tk_6a699aae75094caeb066f****988daa32de",
  "respcd": "0000",
  "token_expiry_date": "2024-04-30 00:00:00",
  "sysdtm": "2024-04-29 15:37:17",
  "notify_type": "payment_token",
  "event": "CONFLICT"
}

​
2️⃣ 訂閱狀態變更通知

當訂閱狀態發生變更時（例如完成、取消），系統會發送此通知。

​
通知類型

notify_type = subscription

​
通知欄位說明

欄位名稱說明
notify_type固定為 subscription
subscription_id訂閱唯一識別碼
state訂閱狀態（ACTIVE / COMPLETED / INCOMPLETE / 等）
sysdtm狀態變更時間

​
範例

Subscription Status Webhook Example
{
  "state": "COMPLETED",
  "sysdtm": "2024-04-24 15:19:39",
  "notify_type": "subscription",
  "subscription_id": "sub_e51bb914919*****f6b0fe36d"
}

​
3️⃣ 訂閱扣款結果通知（Subscription Payment Result）

每次定期扣款嘗試（無論成功或失敗）後，系統都會發送通知。

​
通知類型

notify_type = subscription_payment

​
通知欄位說明

欄位名稱說明
subscription_id訂閱 ID
subscription_order_id扣款訂單 ID（格式：sub_ord_{subscription_id}_{0001}）
respcd回應碼（0000 表示成功）
respmsg回應訊息
syssn系統交易流水號
txdtm交易時間
txamt交易金額
txcurrcd交易幣別
customer_idCustomer ID
product_idProduct ID（多筆以逗號分隔）
cardcd遮罩後卡號
card_scheme卡組織（成功時提供）
current_iteration已完成扣款次數

​
範例

Subscription Payment Webhook Example
{
  "txcurrcd": "HKD",
  "reason": "AUTHORISED",
  "subscription_order_id": "sub_ord_a360f06eb*****ad6aff24c3a",
  "product_id": "prod_8c838c17ddb043b9***11f1a85c30",
  "txdtm": "2024-04-24 15:19:37",
  "txamt": "300",
  "card_scheme": "VISA_DEBIT-SSL",
  "syssn": "20240424180500020000015704",
  "respcd": "0000",
  "subscription_id": "sub_e51bb914919***31d800f6b0fe36d",
  "customer_id": "cust_a9c0bcf2717f4***786a10e5f8f2",
  "notify_type": "subscription_payment",
  "current_iteration": "1"
}

​
Webhook 重試機制與最佳實踐

請確保 Webhook 接收端具備冪等性（Idempotency）設計。
同一事件在通知失敗時可能會被重複發送。
  • 若接收端未回傳 HTTP 200 OK，系統將自動重試
  • 重試採用 指數退避（Exponential Backoff）
  • 實際最大重試次數依內部設定可能有所調整
請務必驗證通知簽名，並僅在驗證成功後更新訂閱或扣款狀態。