Skip to main content

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.

QFPay’s Element SDK enables merchants to build customised checkout experiences using secure, prebuilt payment components hosted by QFPay. It provides flexible front-end integration while keeping payment processing secure and compliant. This guide explains how to integrate the Element SDK into your website or application.

​
Integration Flow

Element Sequence diagram

​
Flow Summary

  1. Create a Payment Intent via QFPay API.
  2. Initialise the SDK using QFpay.config().
  3. Render payment UI (card form or wallet interface).
  4. Collect customer payment details.
  5. Confirm payment using SDK confirmation methods.

​
Supported Payment Methods

The Element SDK supports:
  • Alipay (Mainland China & Hong Kong)
  • WeChat Pay
  • UnionPay / QuickPass
  • FPS
  • PayMe
  • Visa / Mastercard
  • Apple Pay
  • Card Pre-authorisation

​
Step 1: Load SDK

Include the SDK script in your page: 
{/*  Sandbox  */}
<script src="https://cdn-int.qfapi.com/qfpay_element/qfpay.js"></script>

{/*  Live Testing  */}
<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>

​
Step 2: Initialise SDK

const qfpay = QFpay.config({
  region: 'hk',
  env: 'prod'
});
ParameterRequiredValuesDescription
regionNohk | hkt | qaRegion selection
envNoprod | test | qaEnvironment selection
Returns the global qfpay object.

​
Step 3: Create Payment Intent (Backend)

Endpoint POST /payment_element/v1/create_payment_intent

​
Headers

HeaderRequiredDescription
X-QF-APPCODEYesStore app code
X-QF-SIGNYesRequest signature

​
Parameters

ParameterRequiredDescription
txamtYesAmount in cents
txcurrcdNoCurrency (e.g. HKD)
pay_typeYesPayment type code
out_trade_noYesMerchant order number
mchidNoRequired for agent setups
return_urlNoSuccess redirect
failed_urlNoFailure redirect
notify_urlNoWebhook callback

​
Response

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

​
Step 4: Retrieve Payment Intent (Frontend)

const result = qfpay.retrievePaymentIntent();

if (result.code === '0000') {
  console.log('Payment intent valid');
}

​
Step 5: Configure Appearance (Optional)

const elements = qfpay.element({
  theme: 'night',
  variables: {
    colorText: 'black',
    colorPaymentButton: '#000000',
    colorPaymentButtonText: '#FFFFFF'
  },
  billingAddressDisplay: {
    city: true,
    address1: true
  }
});
Use this to customise styling and billing fields.

​
Step 6: Render Payment UI

​
Wallet + Card Interface

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

​
Card Form Only

elements.create('#container');

​
Step 7: Initiate Payment

​
Card Payment

payment.pay({
  goods_name: 'Premium Product',
  paysource: 'payment_element'
}, intentParams.payment_intent);

​
Multi-Wallet Payment

payment.walletPay({
  paysource: 'payment_element_checkout',
  out_trade_no: intentParams.out_trade_no,
  txamt: intentParams.txamt,
  txcurrcd: intentParams.txcurrcd
}, intentParams.payment_intent);

​
Step 8: Confirm Payment

​
Card / Apple Pay

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

​
Wallet Payments

const response = qfpay.confirmWalletPayment({
  return_url: 'https://example.com'
});
CodeMeaning
0000Success
1111Apple Pay cancelled
otherFailed

​
Step 9: Query Transaction

payment.inquiry({
  out_trade_no: intentParams.out_trade_no
}, intentParams.payment_intent);

​
Important Notes

If lang is not specified, the SDK uses the browser language.
Do not place the Element container inside a <form> element. Rendering will fail.
Payment intent expiry:
• Production: 2 years
• Sandbox: 7 days
Always generate signatures and create payment intents from your backend. Never expose secret keys in frontend code.