> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 顧客與 Token 設定

> 建立顧客資料，並透過 Element SDK 產生可重複使用的付款 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](/zh-hant/integration/online-shop/checkout-integration/payment-element) 的步驟渲染卡片付款表單。

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

## 3. 要求建立 Token

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

```js theme={null}
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 通知](/zh-hant/integration/online-shop/integration-by-use-case/saved-payment-methods/token-notification) 確認及保存 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`、建立時間及到期日篩選。

## 下一步

* [付款 Token 通知](/zh-hant/integration/online-shop/integration-by-use-case/saved-payment-methods/token-notification)
* [定期付款](/zh-hant/integration/online-shop/integration-by-use-case/recurring-payments/recurring-overview)