訂閱支付 API 參考 - QFPay Developer Centre

本頁記錄訂閱產品及訂閱管理可使用的 API 端點。開始前請先於儲存付款方式建立並確認付款方式。

前置條件：已儲存的顧客與 Token

請在儲存付款方式建立及管理 customer_id 與 token_id。建立 Subscription 前必須具備已確認的 customer_id 與 token_id。

1. 建立 Product

Endpoint and Method

Create Product

POST /product/v1/create

建立可被訂閱引用的產品（Product）。通常代表一個固定計費方案（例如月費、年費）。

Request Parameters

參數	類型	必填	說明
`name`	String	是	顯示給顧客的產品名稱
`type`	String	是	固定為 `recurring`
`description`	String	否	產品描述
`txamt`	Int	是	金額（最小幣值單位，例如 100 = 1 元）
`txcurrcd`	String	是	幣別，例如 HKD
`interval`	String	是	計費週期，目前支持 `weekly`、`monthly`、`yearly`
`interval_count`	Int	是	週期間隔數，例如週付：`weekly` + 1 月付：`monthly` + 1 季付：`monthly` + 3 半年付：`monthly` + 6 年付：`yearly` + 1（或 `monthly` + 12）
`usage_type`	String	是	固定為 `licensed`

在 Sandbox 環境中，interval 支援 minutes、hours 以方便測試。

Response

回傳新建立的 product_id。

6. 更新 Product

Endpoint and Method

Update Product

POST /product/v1/update

更新產品資料（不影響既有已建立的扣款紀錄，但可能影響後續新扣款計算方式，實際行為以系統設定為準）。

Request Parameters

參數	類型	必填	說明
`product_id`	String	是	產品 ID
`name`	String	否	新的產品名稱
`description`	String	否	新的產品描述

Response

回傳更新筆數。

7. 查詢 Product

Endpoint and Method

Query Product

POST /product/v1/query

依條件查詢 Product 列表（支援分頁）。

Request Parameters

參數	類型	必填	說明
`product_id`	String	否	產品 ID
`name`	String	否	產品名稱
`description`	String	否	產品描述
`txcurrcd`	String	否	交易幣別
`interval`	String	否	計費週期（例如 `monthly` / `yearly`）
`page`	Int	否	頁碼，預設 1
`page_size`	Int	否	每頁筆數，預設 10，最大 100

Response

回傳符合條件的 Product 列表。

8. 刪除 Product

Endpoint and Method

Delete Product

POST /product/v1/delete

刪除指定 Product（需確保該產品未被任何 Subscription 使用中）。

Request Parameters

參數	類型	必填	說明
`product_id`	String	是	要刪除的產品 ID（不可被訂閱關聯）

Response

回傳被刪除的 ID 與結果。

9. 建立 Subscription

建立 Subscription 前，請先確保已完成以下資源：

customer_id
product_id
token_id

Endpoint and Method

Create Subscription

POST /subscription/v1/create

建立新的訂閱計劃。Subscription 建立後，系統會依 start_time（若提供）及產品週期自動排程扣款。

Request Parameters

參數	類型	必填	說明
`customer_id`	String	是	顧客 ID
`token_id`	String	是	支付令牌 ID
`products`	List	是	產品清單（`product_id` + `quantity`）
`total_billing_cycles`	Int	否	總扣款次數；為 null 代表無限期
`start_time`	String	否	訂閱開始時間（亦可作為首次扣款時間）

products 內部參數

欄位	類型	必填	說明
`product_id`	String	是	產品 ID
`quantity`	Int	否	數量，預設 1

Example Request

Create Subscription Request

{
  "products": [
    {
      "product_id": "prod_54c3772d******9a54b236e09ec74f",
      "quantity": 1
    }
  ],
  "customer_id": "cust_aaf6aae94******982c54c9cae5ba32",
  "token_id": "tk_a99892fd*********d3417d168a18bb",
  "total_billing_cycles": 2,
  "start_time": "2020-05-14 12:32:56"
}

Response Parameters（data）

欄位	類型	說明
`subscription_id`	String	訂閱 ID（例如 `sub_xxxxxxxx`）
`state`	String	初始狀態（例如 `ACTIVE` / `INCOMPLETE` / `COMPLETED`）

10. 更新 Subscription

Endpoint and Method

Update Subscription

POST /subscription/v1/update

更新訂閱配置（例如：扣款次數、產品、token、開始時間）。

Request Parameters

參數	類型	必填	說明
`subscription_id`	String	是	訂閱 ID
`total_billing_cycles`	Int	否	總扣款次數（null = 無限）
`start_time`	String	否	訂閱開始時間（影響首次扣款）
`token_id`	String	否	新的支付令牌 ID
`products`	Object	否	產品清單（`product_id` + `quantity`）

Response Parameters（data）

欄位	類型	說明
`subscription_id`	String	訂閱 ID
`rowAffected`	Int	被更新的筆數

11. 查詢 Subscription

Endpoint and Method

Query Subscription

POST /subscription/v1/query

查詢訂閱列表（支援分頁）。

Request Parameters

參數	類型	必填	說明
`page`	Int	否	頁碼，預設 1
`page_size`	Int	否	每頁筆數，預設 10，最大 100
`subscription_id`	String	否	訂閱 ID
`customer_id`	String	否	顧客 ID
`state`	String	否	訂閱狀態（例如 `ACTIVE` / `INCOMPLETE` 等）

Response Parameters（data）

欄位	類型	說明
`subscription_id`	String	訂閱 ID
`customer_id`	String	顧客 ID
`token_id`	String	支付令牌 ID
`products`	Object	產品清單
`total_billing_cycles`	Int	總扣款次數（null = 無限）
`state`	String	訂閱狀態
`next_billing_time`	String	下次扣款時間
`last_billing_time`	String	上次扣款時間
`completed_billing_iteration`	Int	已完成扣款次數
`start_time`	String	訂閱開始時間

12. 取消 Subscription

Endpoint and Method

Cancel Subscription

POST /subscription/v1/cancel

立即取消訂閱。取消後是否仍會完成當期扣款，依實際訂閱設定與渠道規則為準。

Request Parameters

參數	類型	必填	說明
`subscription_id`	String	是	要取消的訂閱 ID

13. 查詢訂閱扣款訂單列表

Endpoint and Method

List Billing Orders

POST /subscription/billing_order/v1/list

查詢指定訂閱下的扣款訂單（每次扣款會對應一筆訂單紀錄）。

Request Parameters

參數	類型	必填	說明
`subscription_id`	String	是	所屬訂閱 ID
`page`	Int	否	頁碼，預設 1
`page_size`	Int	否	每頁筆數，預設 10，最大 100

Response Parameters（data）

欄位	類型	說明
`subscription_order_id`	String	扣款訂單 ID（例如 `sub_ord_{訂閱ID}_{0001}` 代表第 1 次扣款）
`subscription_id`	String	訂閱 ID
`trigger_by`	String	觸發類型：`auto`（系統自動）或 `manual`（手動）
`sequence_no`	Int	該訂閱的第幾次扣款

14. 手動重試扣款（Charge）

Endpoint and Method

Retry Charge

POST /subscription/v1/charge

對失敗的訂閱扣款訂單執行手動扣款重試。

Request Parameters

參數	類型	必填	說明
`subscription_id`	String	是	訂閱 ID
`subscription_order_id`	String	否	（可選）指定要重試的訂單 ID

本 API 只適用於狀態為 UNPAID、INCOMPLETE、PAST_DUE 的訂閱扣款事件。

若重試日期在下一次扣款日前，訂閱會繼續按計劃進行
若重試日期在下一次扣款日之後，訂閱可能被取消（依平台規則為準）
若重試失敗，狀態保持不變

查詢已儲存的付款 Token

POST /token/v1/query 可查詢付款 Token 資料及到期時間。若需查詢特定付款方式，請帶入 customer_id 及 token_id。有關儲存付款方式流程與通知處理，請參閱顧客與 Token 設定。

整合注意事項與最佳實務

建議商戶在後台儲存並關聯：customer_id、product_id、subscription_id、subscription_order_id
請以 Webhook（定期付款通知）作為扣款成功/失敗的主要事件來源，並搭配查詢 API 做補單
Sandbox 可使用更短週期（minutes / hours）驗證重試與狀態流轉，再切換至正式週期（monthly / yearly）

​前置條件：已儲存的顧客與 Token

​1. 建立 Product

​Endpoint and Method

​Request Parameters

​Response

​6. 更新 Product

​Endpoint and Method

​Request Parameters

​Response

​7. 查詢 Product

​Endpoint and Method

​Request Parameters

​Response

​8. 刪除 Product

​Endpoint and Method

​Request Parameters

​Response

​9. 建立 Subscription

​Endpoint and Method

​Request Parameters

​products 內部參數

​Example Request

​Response Parameters（data）

​10. 更新 Subscription

​Endpoint and Method

​Request Parameters

​Response Parameters（data）

​11. 查詢 Subscription

​Endpoint and Method

​Request Parameters

​Response Parameters（data）

​12. 取消 Subscription

​Endpoint and Method

​Request Parameters

​13. 查詢訂閱扣款訂單列表

​Endpoint and Method

​Request Parameters

​Response Parameters（data）

​14. 手動重試扣款（Charge）

​Endpoint and Method

​Request Parameters

​查詢已儲存的付款 Token

​整合注意事項與最佳實務

前置條件：已儲存的顧客與 Token

1. 建立 Product

Endpoint and Method

Request Parameters

Response

6. 更新 Product

Endpoint and Method

Request Parameters

Response

7. 查詢 Product

Endpoint and Method

Request Parameters

Response

8. 刪除 Product

Endpoint and Method

Request Parameters

Response

9. 建立 Subscription

Endpoint and Method

Request Parameters

products 內部參數

Example Request

Response Parameters（data）

10. 更新 Subscription

Endpoint and Method

Request Parameters

Response Parameters（data）

11. 查詢 Subscription

Endpoint and Method

Request Parameters

Response Parameters（data）

12. 取消 Subscription

Endpoint and Method

Request Parameters

13. 查詢訂閱扣款訂單列表

Endpoint and Method

Request Parameters

Response Parameters（data）

14. 手動重試扣款（Charge）

Endpoint and Method

Request Parameters

查詢已儲存的付款 Token

整合注意事項與最佳實務