> ## 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.

# 定期付款概覽

> 簡介 QFPay 定期付款（訂閱支付）架構、核心物件、狀態模型與常見使用情境。

定期付款（Recurring Payments，又稱訂閱支付）允許商戶依固定週期，自動向客戶收取費用，並透過事先儲存的支付令牌（Token）完成扣款。

此模式適合：

* 會員會籍收費
* SaaS 軟體訂閱
* 公用事業帳單
* 設備租賃與分期服務

***

## 什麼是訂閱支付？

訂閱支付是一種長期授權機制，客戶同意商戶在特定週期內重複扣款，可為：

* 固定金額（例如每月 HKD 100）
* 或依產品設定的固定週期計費

在 QFPay 系統中，訂閱由 `subscription` 物件表示，並連結以下核心元素：

* `customer_id`
* `token_id`
* `product_id`

***

## 核心物件說明

| 物件                | 說明                              |
| ----------------- | ------------------------------- |
| `customer_id`     | 顧客資料，用於識別被扣款對象                  |
| `token_id`        | 已儲存的付款方式（透過 Payment Element 取得） |
| `product_id`      | 定義收費金額、幣別與週期                    |
| `subscription_id` | 訂閱主體，整合上述三者並控制扣款排程              |

***

## 訂閱支付完整流程

### 1️⃣ 建立 Customer

透過 API：

```http Create Customer theme={null}
POST /customer/v1/create
```

建立顧客資料並取得 `customer_id`。

***

### 2️⃣ 產生支付令牌（Token）

使用 Payment Element 收集卡片資訊，取得 `token_id`。

此步驟僅建立授權扣款能力，不會立即扣款。

***

### 3️⃣ 建立 Product

透過 API：

```http Create Product theme={null}
POST /product/v1/create
```

定義：

* 每期金額
* 幣別
* 收費週期（例如 monthly / yearly）

***

### 4️⃣ 建立 Subscription

透過 API：

```http Create Subscription theme={null}
POST /subscription/v1/create
```

傳入：

* `customer_id`
* `product_id`
* `token_id`

建立成功後，系統會依產品週期自動排程扣款。

***

### 5️⃣ 自動扣款與補扣

* 系統依週期自動扣款
* 若扣款失敗，可使用：

```http Manual Charge theme={null}
POST /subscription/v1/charge
```

對失敗訂單進行手動補扣

***

## 訂閱狀態說明

| 狀態           | 說明                   |
| ------------ | -------------------- |
| `ACTIVE`     | 訂閱正常運行，依排程扣款         |
| `INCOMPLETE` | 訂閱建立未完成（例如 Token 無效） |
| `PAST_DUE`   | 曾有扣款失敗               |
| `CANCELLED`  | 已取消訂閱                |
| `COMPLETED`  | 已完成所有扣款週期            |

<Note>
  建議整合 Webhook 通知，以即時接收訂閱狀態變更與扣款結果。
</Note>

***

## 常見使用情境

* **健身會籍**：每月 HKD 300
* **SaaS 訂閱**：每月 HKD 98 或每年 HKD 999
* **設備租賃**：固定期數扣款並支援補扣

***

## 常見問題

### 可以更新訂閱的付款方式嗎？

可以。\
使用：

```http Update Subscription theme={null}
POST /subscription/v1/update
```

替換新的 `token_id`。

***

### 可以暫停訂閱嗎？

目前不支援暫停。\
可先取消，再重新建立訂閱。

***

### 可以補扣失敗的款項嗎？

可以。\
使用 `/subscription/v1/charge` 並傳入失敗的 `subscription_order_id`。

***

## 下一步

* 訂閱 API 參考文件
* Webhook 通知整合指南
* Payment Element SDK 整合說明