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

​
整合流程總覽

Element Sequence diagram
  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： 
{/*  測試環境（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 | hkt區域代碼：hk 表示香港正式環境，hkt 表示線上測試環境，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 天。