跳轉到主要內容
本頁記錄定期付款可使用的 API 端點。開始前請先閱讀「定期付款概覽」，了解整體流程與必要條件（例如：Customer、Product、Token、Subscription 的關係，以及扣款失敗後的處理策略）。

​
何時使用

以下情境適合使用本頁 API：
  • 建立顧客資料（Customer）與訂閱產品（Product）
  • 以已綁定的支付令牌（Token）建立訂閱（Subscription）
  • 更新 / 取消訂閱
  • 查詢訂閱狀態、下次扣款時間、扣款訂單列表
  • 對失敗扣款執行手動重試（Charge）

​
1. 建立 Customer

​
Endpoint and Method

Create Customer
POST /customer/v1/create
建立一筆新的顧客資料（Customer）。
此 customer_id 會在後續建立 Subscription 時被引用，用於將訂閱關聯到指定顧客。

​
Request Parameters

參數類型必填說明
customer_idString是顧客 ID（由商戶系統生成並保持唯一）
nameString否顧客姓名
phoneString否聯絡電話
emailString否電郵地址
billing_addressString (JSON)否帳單地址（JSON 字串）

​
Response

回傳 customer_id。

​
2. 更新 Customer

​
Endpoint and Method

Update Customer
POST /customer/v1/update
更新既有顧客資料（以 customer_id 為主鍵）。

​
Request Parameters

參數類型必填說明
customer_idString是顧客 ID
nameString否新的姓名
phoneString否新的電話
emailString否新的電郵地址
billing_addressJSON否帳單地址 JSON 物件

​
Response

回傳更新筆數。

​
3. 查詢 Customer

​
Endpoint and Method

Query Customer
POST /customer/v1/query
依條件查詢 Customer 列表（支援分頁）。

​
Request Parameters

參數類型必填說明
customer_idString否顧客 ID
nameString否姓名
phoneString否聯絡電話
emailString否電郵
pageInt否頁碼，預設 1
page_sizeInt否每頁筆數，預設 10，最大 100

​
Response

回傳符合條件的 Customer 列表。

​
4. 刪除 Customer

​
Endpoint and Method

Delete Customer
POST /customer/v1/delete
刪除指定 Customer。此操作無法還原。

​
Request Parameters

參數類型必填說明
customer_idString是要刪除的顧客 ID

​
Response

回傳被刪除的 ID 與結果。

​
5. 建立 Product

​
Endpoint and Method

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

​
Request Parameters

參數類型必填說明
nameString是顯示給顧客的產品名稱
typeString是固定為 recurring
descriptionString否產品描述
txamtInt是金額（最小幣值單位，例如 100 = 1 元）
txcurrcdString是幣別，例如 HKD
intervalString是計費週期，例如 monthly、yearly
interval_countInt是週期間隔數，例如 1 = 每月；12 = 每年
usage_typeString是固定為 licensed
在 Sandbox 環境中，interval 支援 minutes、hours 以方便測試。

​
Response

回傳新建立的 product_id。

​
6. 更新 Product

​
Endpoint and Method

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

​
Request Parameters

參數類型必填說明
product_idString是產品 ID
nameString否新的產品名稱
descriptionString否新的產品描述

​
Response

回傳更新筆數。

​
7. 查詢 Product

​
Endpoint and Method

Query Product
POST /product/v1/query
依條件查詢 Product 列表（支援分頁）。

​
Request Parameters

參數類型必填說明
product_idString否產品 ID
nameString否產品名稱
descriptionString否產品描述
txcurrcdString否交易幣別
intervalString否計費週期（例如 monthly / yearly）
pageInt否頁碼，預設 1
page_sizeInt否每頁筆數，預設 10，最大 100

​
Response

回傳符合條件的 Product 列表。

​
8. 刪除 Product

​
Endpoint and Method

Delete Product
POST /product/v1/delete
刪除指定 Product（需確保該產品未被任何 Subscription 使用中）。

​
Request Parameters

參數類型必填說明
product_idString是要刪除的產品 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_idString是顧客 ID
token_idString是支付令牌 ID
productsList是產品清單（product_id + quantity）
total_billing_cyclesInt否總扣款次數；為 null 代表無限期
start_timeString否訂閱開始時間（亦可作為首次扣款時間）

​
products 內部參數

欄位類型必填說明
product_idString是產品 ID
quantityInt否數量，預設 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_idString訂閱 ID（例如 sub_xxxxxxxx）
stateString初始狀態（例如 ACTIVE / INCOMPLETE / COMPLETED）

​
10. 更新 Subscription

​
Endpoint and Method

Update Subscription
POST /subscription/v1/update
更新訂閱配置（例如：扣款次數、產品、token、開始時間）。

​
Request Parameters

參數類型必填說明
subscription_idString是訂閱 ID
total_billing_cyclesInt否總扣款次數（null = 無限）
start_timeString否訂閱開始時間（影響首次扣款）
token_idString否新的支付令牌 ID
productsObject否產品清單（product_id + quantity）

​
Response Parameters（data）

欄位類型說明
subscription_idString訂閱 ID
rowAffectedInt被更新的筆數

​
11. 查詢 Subscription

​
Endpoint and Method

Query Subscription
POST /subscription/v1/query
查詢訂閱列表（支援分頁）。

​
Request Parameters

參數類型必填說明
pageInt否頁碼，預設 1
page_sizeInt否每頁筆數，預設 10，最大 100
subscription_idString否訂閱 ID
customer_idString否顧客 ID
stateString否訂閱狀態（例如 ACTIVE / INCOMPLETE 等）

​
Response Parameters（data）

欄位類型說明
subscription_idString訂閱 ID
customer_idString顧客 ID
token_idString支付令牌 ID
productsObject產品清單
total_billing_cyclesInt總扣款次數（null = 無限）
stateString訂閱狀態
next_billing_timeString下次扣款時間
last_billing_timeString上次扣款時間
completed_billing_iterationInt已完成扣款次數
start_timeString訂閱開始時間

​
12. 取消 Subscription

​
Endpoint and Method

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

​
Request Parameters

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

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

​
Endpoint and Method

List Billing Orders
POST /subscription/billing_order/v1/list
查詢指定訂閱下的扣款訂單（每次扣款會對應一筆訂單紀錄）。

​
Request Parameters

參數類型必填說明
subscription_idString是所屬訂閱 ID
pageInt否頁碼，預設 1
page_sizeInt否每頁筆數，預設 10，最大 100

​
Response Parameters（data）

欄位類型說明
subscription_order_idString扣款訂單 ID（例如 sub_ord_{訂閱ID}_{0001} 代表第 1 次扣款）
subscription_idString訂閱 ID
trigger_byString觸發類型：auto（系統自動）或 manual（手動）
sequence_noInt該訂閱的第幾次扣款

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

​
Endpoint and Method

Retry Charge
POST /subscription/v1/charge
對失敗的訂閱扣款訂單執行手動扣款重試。

​
Request Parameters

參數類型必填說明
subscription_idString是訂閱 ID
subscription_order_idString否（可選）指定要重試的訂單 ID
本 API 只適用於狀態為 UNPAID、INCOMPLETE、PAST_DUE 的訂閱扣款事件。
  • 若重試日期在下一次扣款日前，訂閱會繼續按計劃進行
  • 若重試日期在下一次扣款日之後，訂閱可能被取消（依平台規則為準）
  • 若重試失敗，狀態保持不變

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

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