支付組件 (Element) SDK

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

整合流程總覽

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

支援的支付方式

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

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

整合步驟

步驟一：引入 SDK JavaScript 檔案

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

{/*  測試環境（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 並設定所需的區域與環境參數。

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

回應範例

{
  "respcd": "0000",
  "payment_intent": "38aec7ce...",
  "intent_expiry": "2026-01-01 12:00:00"
}

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

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

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 設定物件來自訂外觀風格。

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()` 建立錢包 + 信用卡介面（進階選單式）

const elements = qfpay.element(appearance);

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

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

elements.create("#container");

步驟七：執行付款

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

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()` 收集錢包 + 信用卡支付資料

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);

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

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

elements.createWallet({ selector: '#container' });

步驟八：確認付款

確認信用卡 / Apple Pay 付款

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

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

確認多錢包付款

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

成功交易常見回傳欄位：

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

步驟九：查詢交易結果

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);

注意事項

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

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

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

準備

商業場景

API 參考文件

實體店支付

線上支付

共用端點

整合流程總覽

支援的支付方式

整合步驟

步驟一：引入 SDK JavaScript 檔案

步驟二：初始化 SDK

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

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

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

渲染付款介面

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

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

步驟七：執行付款

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

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

步驟八：確認付款

確認信用卡 / Apple Pay 付款

確認多錢包付款

步驟九：查詢交易結果

注意事項

​整合流程總覽

​支援的支付方式

​整合步驟

​步驟一：引入 SDK JavaScript 檔案

​步驟二：初始化 SDK

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

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

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

​渲染付款介面

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

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

​步驟七：執行付款

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

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

​步驟八：確認付款

​確認信用卡 / Apple Pay 付款

​確認多錢包付款

​步驟九：查詢交易結果

​注意事項

整合流程總覽

支援的支付方式

整合步驟

步驟一：引入 SDK JavaScript 檔案

步驟二：初始化 SDK

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

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

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

渲染付款介面

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

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

步驟七：執行付款

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

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

步驟八：確認付款

確認信用卡 / Apple Pay 付款

確認多錢包付款

步驟九：查詢交易結果

注意事項