跳轉到主要內容
本指南說明如何整合 QFPay 訂閱支付（定期付款），包含必要條件、建議的 API 呼叫順序，以及正式環境常見的設計與最佳實踐。

​
前置條件

開始前請確認：
  • 已取得 API 憑證：AppCode、AppKey
  • 已設定 notify_url（Webhook 接收端），可接收訂閱相關事件
  • 前端可整合並渲染 Payment Element（用於建立付款 Token）

​
整合流程總覽

建議依以下順序整合：
  1. 設定 Webhook 接收端：接收 payment_token、subscription、subscription_payment 通知
  2. 建立 Customer：取得 customer_id
  3. 前端渲染 Payment Element：呼叫 payment.pay() 並帶入 customer_id 以建立付款 token
  4. 取得 token_id：透過 Webhook 通知（或 API 回應）取得 token
  5. 建立 Product：定義每期金額、幣別、週期與間隔
  6. 建立 Subscription：傳入 customer_id、token_id 與 product_id
  7. （選用）監控訂閱狀態：透過 Webhook 或查詢 API 同步訂閱狀態

​
資料模型建議

整合時建議在商戶系統保存以下關聯（便於後續查詢、補扣、報表與客服）：
  • customer_id：顧客識別
  • token_id：付款令牌（代表已授權的扣款方式）
  • product_id：訂閱產品（定價與週期）
  • subscription_id：訂閱主體
  • subscription_order_id：每次扣款的訂閱訂單（用於失敗重試與查核）

​
Webhook 設計建議

建議將 Webhook 作為「狀態變更的主要來源」，並搭配查詢 API 作補單：
  • Webhook 到達：更新訂閱 / 扣款狀態
  • Webhook 未到 / 延遲：用查詢 API 追狀態並修正
Webhook 資料請務必做簽名驗證（Signature Verification），避免依賴未驗證事件更新訂單或開通服務。

​
最佳實踐

建議使用「查詢 Subscription」API 定期同步訂閱狀態到 CRM / 後台系統，避免僅依賴單次 Webhook。
每次建立訂閱後，請確認已收到 Webhook，且訂閱狀態為 ACTIVE 或 INCOMPLETE，以確認建立成功並可追蹤後續扣款。
請務必在資料庫中保存 subscription_id 與 token_id，以支援後續的扣款重試、取消訂閱、對賬與報表需求。

​
下一步

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