本頁說明 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

通知欄位說明

欄位名稱	說明
`userid`	QFPay 門店 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_id`	Customer ID
`product_id`	Product 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）
實際最大重試次數依內部設定可能有所調整

請務必驗證通知簽名，並僅在驗證成功後更新訂閱或扣款狀態。

準備

商業場景

API 參考文件

實體店支付

線上支付

共用端點

訂閱支付 Webhook（定期付款通知）

如何設定 Webhook URL

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

通知類型

通知欄位說明

範例

2️⃣ 訂閱狀態變更通知

通知類型

通知欄位說明

範例

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

通知類型

通知欄位說明

範例

Webhook 重試機制與最佳實踐

​如何設定 Webhook URL

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

​通知類型

​通知欄位說明

​範例

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

​通知類型

​通知欄位說明

​範例

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

​通知類型

​通知欄位說明

​範例

​Webhook 重試機制與最佳實踐

如何設定 Webhook URL

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

通知類型

通知欄位說明

範例

2️⃣ 訂閱狀態變更通知

通知類型

通知欄位說明

範例

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

通知類型

通知欄位說明

範例

Webhook 重試機制與最佳實踐