顧客與 Token 設定

本指南說明在定期付款或其他支援的後續付款流程前，需要完成的共用設定。

1. 建立顧客資料

在收集付款方式前，先建立顧客資料。 POST /customer/v1/create

參數	類型	必填	說明
`name`	String	否	顧客姓名。
`phone`	String	否	聯絡電話。
`email`	String	否	電郵地址。
`billing_address`	String (JSON)	否	帳單地址的 JSON 字串。

回應會傳回 customer_id。請在後端保存此值，並於 Element SDK 卡片付款時使用。

2. 建立 Payment Intent

請由後端建立 Payment Intent，再依照 Element SDK 的步驟渲染卡片付款表單。

Payment Intent 及簽名必須由後端建立。請勿在瀏覽器程式碼中暴露商戶密鑰。

3. 要求建立 Token

付款 Token 僅支援透過 payment.pay() 發起的卡片付款。呼叫時帶入 customer_id 及選用的 Token 欄位。

payment.pay({
  goods_name: 'Premium Product',
  paysource: 'payment_element',
  customer_id: 'cust_aaf6aae94...',
  token_expiry: '2026-01-01',
  token_reason: 'Save Card',
  token_reference: 'customer-123'
}, intentParams.payment_intent);

參數	必填	說明
`customer_id`	建立 Token 時必填	與付款 Token 關聯的 QFPay 顧客 ID。
`token_expiry`	否	產生 Token 時的指定到期日。
`token_reason`	否	建立 Token 的原因。
`token_reference`	否	商戶對賬或追蹤參考編號。

4. 確認卡片付款

以 qfpay.confirmPayment() 完成付款。成功回應可能包含 token_id。請勿只依賴瀏覽器回應作為最終結果，應以付款 Token 通知確認及保存 Token。

管理顧客資料

使用以下 API 管理已儲存付款方式關聯的顧客資料：

操作	Endpoint	用途
更新顧客	`POST /customer/v1/update`	更新姓名、電話、電郵或帳單地址。
查詢顧客	`POST /customer/v1/query`	依顧客 ID 或聯絡資料搜尋顧客。
刪除顧客	`POST /customer/v1/delete`	刪除顧客資料，此操作無法還原。

查詢已儲存的 Token

POST /token/v1/query 使用 customer_id 與 token_id 查詢付款 Token 的詳細資料及到期時間。您亦可依 reason、reference、建立時間及到期日篩選。

準備

商業場景

API 參考文件

實體店支付

線上支付

共用端點

1. 建立顧客資料

2. 建立 Payment Intent

3. 要求建立 Token

4. 確認卡片付款

管理顧客資料

查詢已儲存的 Token

下一步

​1. 建立顧客資料

​2. 建立 Payment Intent

​3. 要求建立 Token

​4. 確認卡片付款

​管理顧客資料

​查詢已儲存的 Token

​下一步

1. 建立顧客資料

2. 建立 Payment Intent

3. 要求建立 Token

4. 確認卡片付款

管理顧客資料

查詢已儲存的 Token

下一步