> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 說明 QFPay 訂閱支付的 Webhook 非同步通知機制，包括 Token 建立、訂閱狀態變更與定期扣款結果。

本頁說明 QFPay 在訂閱支付流程中所發送的非同步通知（Webhook）。\
主要涵蓋以下三類事件：

* `payment_token`：支付令牌建立
* `subscription`：訂閱狀態變更
* `subscription_payment`：定期扣款結果

***

## 如何設定 Webhook URL

<Note>
  若需設定或修改 Webhook 接收端點，請將以下資訊提供給 QFPay 技術支援：

  * Webhook URL
  * 商戶 ID
  * 門店 ID
</Note>

***

# 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`   | 系統內部令牌參考值                       |

***

## 範例

```json Token Webhook Example theme={null}
{
  "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`          | 狀態變更時間                                          |

***

## 範例

```json Subscription Status Webhook Example theme={null}
{
  "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`     | 已完成扣款次數                                        |

***

## 範例

```json Subscription Payment Webhook Example theme={null}
{
  "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 重試機制與最佳實踐

<Tip>
  請確保 Webhook 接收端具備**冪等性（Idempotency）設計**。\
  同一事件在通知失敗時可能會被重複發送。
</Tip>

* 若接收端未回傳 **HTTP 200 OK**，系統將自動重試
* 重試採用 **指數退避（Exponential Backoff）**
* 實際最大重試次數依內部設定可能有所調整

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