> ## 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.

# 支付組件 (Element) SDK

> 使用 QFPay 的 Element SDK，在您的網站中嵌入卡支付或多錢包 UI，保留靈活度的同時確保安全性。

QFPay 的 **支付組件 SDK** 讓您能夠使用 QFPay 提供的預建 UI 元件，自行建立結帳流程。這是一種靈活的前端整合方式，適合希望在保留安全託管邏輯的同時，擁有更多自訂體驗的商戶。

本指南將說明如何將 QFPay 的託管支付組件 SDK 整合至您的網站或應用程式中。

***

## 整合流程總覽

![Element Sequence diagram](https://www.plantuml.com/plantuml/png/VLF1ZXCn3BtdAwozmuAuzO1s0Qs4458H7r0bgQTZTPBCEiukvUjn9bEbhO1BbTX-p--zPXwoM9OI9cEz90PVigI033OlPpDhcppDDWhSVKVsOpqzSOg2SG-VH_J7L0Isze1t5HM6Vs0-MNzKI1jorqC_dhRs13XXGBt-_F9jcNeUjFAtmKvLXvpUZ36sI8ebE6HJbSERZwfb0_wiK0rIYYOCIyTTT1YV2whNu6gh4MgRqGh2R4-BAAg6nSIaDQR3AEPn-tK3zsj_jug_Vtb_tv2xSsT5rhWgsZ1AuVWVukiElD8qWKF0NpCnxhKC7zv1e5W4SwSDxcnvNT2okYPhzbko6wsHa9teDuAtl8SXST1rCjwYMg8TE5H9CgumYXLeQxpNqK_aZv2B2oJWYaYApUQ4WvWARqK82geEASmjHNNfJX3MfzCztgX_IKVKcufzwrCSYCDsrJsKw8MkzhLKTeMdwXCqIMBq0dFXEMNiInRw_X3MBFepQVKB8NqWbqaQlcNGUpvLRsgiJiqfwi83fp833N2XZ39alA4uA-qVfwHBp2kwJB8OC2lfOpv5FtAAgUHgYWRoxV_fueFhwdBn7lFDQELxq9yIfZy0)

1. 使用 QFPay 的 API 建立 Payment Intent（支付意圖）。
2. 使用 `QFpay.config()` 初始化 SDK。
3. 選擇支付模式：信用卡表單（`elements.createEnhance`）或多錢包介面（`elements.createWallet`）。
4. 向顧客收集支付資料。
5. 使用 QFPay 後端 API 進行確認（`confirmPayment()` 或 `confirmWalletPayment()`）。

***

## 支援的支付方式

支付組件 SDK 支援以下支付方式：

* 支付寶（中國大陸、香港）
* 微信支付
* 銀聯 / 雲閃付
* 轉數快（FPS）
* PayMe
* Visa / MasterCard
* Apple Pay
* Visa / MasterCard 預授權

***

## 整合步驟

### 步驟一：引入 SDK JavaScript 檔案

請在您的 HTML 中加入以下 `<script>` 標籤以載入 SDK：

```html theme={null}
{/*  測試環境（Sandbox）  */}
<script src="https://cdn-int.qfapi.com/qfpay_element/qfpay.js"></script>

{/*  線上測試環境（Live Test）  */}
<script src="https://test-cdn-hk.qfapi.com/qfpay_element/qfpay.js"></script>

{/*  正式環境（Production）  */}
<script src="https://cdn-hk.qfapi.com/qfpay_element/qfpay.js"></script>
```

***

### 步驟二：初始化 SDK

初始化 SDK 並設定所需的區域與環境參數。

```js theme={null}
const qfpay = QFpay.config({
  region: 'hk',
  env: 'prod'
});
```

| 參數       | 是否必填 | 可選值                      | 說明                                         |
| -------- | ---: | ------------------------ | ------------------------------------------ |
| `region` |    否 | `hk` \| `qa`             | 區域代碼：`hk` 表示香港正式環境，`qa` 表示沙盒測試環境。          |
| `env`    |    否 | `prod` \| `test` \| `qa` | 環境設定：`prod` 為正式環境，`test` 為測試環境，`qa` 為沙盒環境。 |

回傳全域的 `qfpay` 物件，用於後續操作。

***

### 步驟三：建立 Payment Intent（後端 API）

**端點**：`/payment_element/v1/create_payment_intent`\
**方法**：`POST`

**Headers**

| 標頭名稱           | 是否必填 | 說明          |
| -------------- | ---: | ----------- |
| `X-QF-APPCODE` |    是 | 商戶 App Code |
| `X-QF-SIGN`    |    是 | 簽名值         |

**Request Parameters**

| 參數名稱           | 是否必填 | 說明                  |
| -------------- | ---: | ------------------- |
| `txamt`        |    是 | 支付金額（單位：分），建議 > 200 |
| `txcurrcd`     |    否 | 幣別，例如 `HKD`         |
| `pay_type`     |    是 | 支付類型代碼              |
| `out_trade_no` |    是 | 訂單號 / 商戶平台訂單編號      |
| `mchid`        |    否 | 商戶 ID（代理商適用）        |
| `return_url`   |    否 | 支付成功跳轉網址            |
| `failed_url`   |    否 | 支付失敗跳轉網址            |
| `notify_url`   |    否 | 支付結果通知 webhook      |

**回應範例**

```json theme={null}
{
  "respcd": "0000",
  "payment_intent": "38aec7ce...",
  "intent_expiry": "2026-01-01 12:00:00"
}
```

***

### 步驟四：驗證 Payment Intent（前端）

在後端建立 payment intent 後，請在前端呼叫下列方法進行驗證：

```js theme={null}
const qfpay = QFpay.config();
const result = qfpay.retrievePaymentIntent();

if (result.code === '0000') {
  console.log('Payment intent is valid');
} else {
  console.error('Invalid or expired payment intent');
}
```

***

### 步驟五：設定外觀樣式（可選）

初始化 UI 元件處理器，用於渲染卡片表單或錢包介面。你可以傳入 `appearance` 設定物件來自訂外觀風格。

```js theme={null}
const appearance = {
  theme: 'night',
  variables: {
    fontFamily: 'cursive',
    fontWeight: '400',
    colorText: 'black',
    sizeFontSubTitle: 'inherit',
    colourBackground: '#fff',
    colourPrimary: '#ced4da',
    colourComponentText: 'purple',
    sizeComponentText: '15px',
    colourErrorMessage: '#da5d4a',
    sizeErrorMessage: 'inherit',
    colorPaymentButton: '#000000',
    colorPaymentButtonText: '#FFFFFF',
    colorQRCodeTopPromptContent: '#000000',
    colorQRCodeBottomPromptContent: '#000000',
    fontWeightQRCodeTopPrompt: '900',
    fontWeightQRCodeBottomPrompt: '300'
  },
  billingAddressDisplay: {
    city: true,
    address1: true,
    address2: true
  }
};

const elements = qfpay.element(appearance);
```

***

### 渲染付款介面

#### 使用 `elements.createEnhance()` 建立錢包 + 信用卡介面（進階選單式）

```js theme={null}
const elements = qfpay.element(appearance);

elements.createEnhance({
  selector: '#container',
  email: true,
  tab: true,
  element: 'payment',
  lang: 'en'
});
```

#### 使用 `elements.create()` 僅建立信用卡表單

```js theme={null}
elements.create("#container");
```

***

### 步驟七：執行付款

#### 使用 `payment.pay()` 收集信用卡支付資料

```js theme={null}
payment.pay({
  goods_name: 'Premium Product',
  paysource: 'payment_element',
  customer_id: 'CUST123456',
  token_expiry: '2026-01-01',
  token_reason: 'Recurring Setup',
  token_reference: 'INV-0987'
}, intentParams.payment_intent);
```

#### 使用 `payment.walletPay()` 收集錢包 + 信用卡支付資料

```js theme={null}
payment.walletPay({
  lang: 'en',
  goods_info: 'Premium membership',
  goods_name: 'VIP Access',
  paysource: 'payment_element_checkout',
  out_trade_no: intentParams.out_trade_no,
  txamt: intentParams.txamt,
  txcurrcd: intentParams.txcurrcd,
  support_pay_type: [
    'Alipay',
    'AlipayHK',
    'WeChat',
    'FPS',
    'UnionPay',
    'PayMe',
    'VisaMasterCardPayment',
    'ApplePay',
    'VisaMasterCardPreAuth'
  ],
  customer_id: 'CUST123456',
  token_expiry: '2026-01-01',
  token_reason: 'Subscription',
  token_reference: 'SUB20241101'
}, intentParams.payment_intent);
```

<Note>
  <ul>
    <li>`txamt`、`txcurrcd` 與 `out_trade_no` 建議由後端建立 Payment Intent 時一併生成並回傳前端。</li>
    <li>如未指定 `support_pay_type`，將依商戶已開通配置顯示可用支付方式。</li>
    <li>此方法不會回傳交易結果；請配合 `qfpay.confirmWalletPayment()<` 完成付款確認。</li>
  </ul>
</Note>

呼叫完 `walletPay()` 後，使用 `elements.createWallet()` 把支付 UI 插入畫面容器：

```js theme={null}
elements.createWallet({ selector: '#container' });
```

***

### 步驟八：確認付款

#### 確認信用卡 / Apple Pay 付款

```js theme={null}
const paymentResponse = qfpay.confirmPayment({
  return_url: 'https://example.com'
});
```

| 代碼     | 含義              | 備註                |
| ------ | --------------- | ----------------- |
| `0000` | 付款成功            | —                 |
| `1111` | 用戶取消（Apple Pay） | 僅適用於 Apple Pay    |
| 其他     | 付款失敗            | 請參考 `description` |

#### 確認多錢包付款

```js theme={null}
const paymentResponse = qfpay.confirmWalletPayment({
  return_url: 'https://example.com'
});
```

成功交易常見回傳欄位：

* `code`：`0000` 表示成功
* `description`：結果描述
* `out_trade_no`：商戶訂單號
* `syssn`：QFPay 交易 ID

***

### 步驟九：查詢交易結果

```js theme={null}
const inquiryResponse = payment.inquiry({
  syssn: '20251201...',
  out_trade_no: intentParams.out_trade_no,
  pay_type: 'VisaMasterCardPayment',
  respcd: '0000',
  start_time: '2025-01-01 00:00:00',
  end_time: '2025-01-31 23:59:59'
}, intentParams.payment_intent);
```

***

## 注意事項

<Tip>
  若未傳入 `lang` 參數，系統將自動採用瀏覽器預設語言。
</Tip>

<Warning>
  Element 容器不可嵌套於 `<form>` 標籤內，否則元件可能無法正確渲染。
</Warning>

<Info>
  付款意圖有效期限：正式環境為 2 年，沙盒環境為 7 天。
</Info>