跳轉到主要內容
定期付款（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：
Create Customer
POST /customer/v1/create
建立顧客資料並取得 customer_id。

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

使用 Payment Element 收集卡片資訊，取得 token_id。 此步驟僅建立授權扣款能力，不會立即扣款。

​
3️⃣ 建立 Product

透過 API：
Create Product
POST /product/v1/create
定義：
  • 每期金額
  • 幣別
  • 收費週期（例如 monthly / yearly）

​
4️⃣ 建立 Subscription

透過 API：
Create Subscription
POST /subscription/v1/create
傳入：
  • customer_id
  • product_id
  • token_id
建立成功後，系統會依產品週期自動排程扣款。

​
5️⃣ 自動扣款與補扣

  • 系統依週期自動扣款
  • 若扣款失敗，可使用：
Manual Charge
POST /subscription/v1/charge
對失敗訂單進行手動補扣

​
訂閱狀態說明

狀態說明
ACTIVE訂閱正常運行，依排程扣款
INCOMPLETE訂閱建立未完成（例如 Token 無效）
PAST_DUE曾有扣款失敗
CANCELLED已取消訂閱
COMPLETED已完成所有扣款週期
建議整合 Webhook 通知，以即時接收訂閱狀態變更與扣款結果。

​
常見使用情境

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

​
常見問題

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

可以。
使用：
Update Subscription
POST /subscription/v1/update
替換新的 token_id。

​
可以暫停訂閱嗎？

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

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

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

​
下一步

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