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. The Element SDK supports standard payments as well as saving a customer’s payment method for supported future token-based payment scenarios. This guide explains how to integrate the Element SDK into your website or application.

Integration Flow

Flow Summary

Create a Payment Intent via QFPay API.
Initialise the SDK using QFpay.config().
Render the payment UI.
Collect customer payment details.
Initiate the payment using payment.pay() or payment.walletPay().
Confirm the payment using confirmPayment() or confirmWalletPayment().
If customer_id is provided, QFPay also generates a token_id for the saved payment method.

Saving a payment method is optional.If customer_id is not provided, the payment is processed as a standard payment and no payment token is generated.

Supported Payment Methods

The Element SDK supports:

Alipay (Mainland China & Hong Kong)
WeChat Pay
UnionPay / QuickPass
FPS
PayMe
Visa / Mastercard
Apple Pay
Visa / Mastercard Pre-authorisation

Integration Steps

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

Initialise the SDK and configure the required region and environment.

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

Parameter	Required	Values	Description
`region`	No	`hk` \| `qa`	Region selection. `hk` represents the Hong Kong production environment and `qa` represents the sandbox environment.
`env`	No	`prod` \| `test` \| `qa`	Environment selection. `prod` is production, `test` is live testing, and `qa` is sandbox.

Returns the global qfpay object for subsequent SDK operations.

Step 3: Create Payment Intent (Backend)

Endpoint: /payment_element/v1/create_payment_intent Method: POST

Headers

Header	Required	Description
`X-QF-APPCODE`	Yes	Merchant App Code
`X-QF-SIGN`	Yes	Request signature

Request Parameters

Parameter	Required	Description
`txamt`	Yes	Payment amount in cents (recommended > 200).
`txcurrcd`	No	Currency, e.g. `HKD`.
`pay_type`	Yes	Payment type code.
`out_trade_no`	Yes	Merchant order number.
`mchid`	No	Merchant ID (required for agent setups).
`return_url`	No	Redirect URL after successful payment.
`failed_url`	No	Redirect URL after failed payment.
`notify_url`	No	Webhook URL for payment result notifications.

Response Example

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

Step 4: Retrieve Payment Intent (Frontend)

After your backend creates the Payment Intent, retrieve and validate it from the frontend.

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

Step 5: Configure Appearance (Optional)

Initialise the UI element handler for rendering the card form or multi-payment interface. You can provide an appearance object to customise the styling and displayed billing address fields.

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

Step 6: Render Payment UI

Enhanced Payment Interface (Wallet + Card)

Use elements.createEnhance() to render an enhanced payment interface that supports multiple payment methods.

const elements = qfpay.element(appearance);

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

Card Payment Form Only

Use elements.create() to render a card-only payment form.

elements.create('#container');

Step 7: Initiate Payment

Card Payment

Use payment.pay() to collect card payment details and initiate the payment.

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

Multi-Payment Interface

Use payment.walletPay() to initialise the multi-payment interface.

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'
  ]
}, intentParams.payment_intent);

After calling walletPay(), render the payment interface by calling:

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

txamt, txcurrcd, and out_trade_no should preferably be generated together with the Payment Intent by your backend and returned to the frontend.
If support_pay_type is omitted, the SDK displays all payment methods enabled for the merchant.
walletPay() does not return the final transaction result. Complete the payment flow by calling qfpay.confirmWalletPayment().

Optional: Generate a Payment Token (Card Payments Only)

Payment token generation is currently supported only for card payments initiated using payment.pay().Payment tokens are not generated for wallet payment methods.

The Element SDK supports saving a customer’s payment method during a successful payment. To request payment token creation, provide customer_id when calling payment.pay() or payment.walletPay(). When customer_id is provided and the payment is completed successfully, QFPay generates a payment token and returns a token_id associated with the customer.

Saving a payment method is optional.If customer_id is not provided, the payment will be processed normally and no token_id will be generated.

Token Creation Flow

Create a Payment Intent.
Render the payment interface using the Element SDK.
The customer enters their payment details.
Initiate a card payment using payment.pay() with customer_id.
The customer completes the payment.
QFPay generates a payment token.
A token_id is returned.
Store the token_id securely in your backend.

Token Parameters

The following parameters are available when initiating a card payment using payment.pay().

Parameter	Required	Description
`customer_id`	Yes (for token creation)	Merchant-defined customer identifier. When provided, QFPay generates a payment token after a successful payment.
`token_expiry`	No	Expiry date of the generated payment token.
`token_reason`	No	Merchant-defined reason for creating the payment token.
`token_reference`	No	Merchant-defined reference for reconciliation or internal tracking.

Example - Card Payment

payment.pay({
  goods_name: 'Premium Product',
  paysource: 'payment_element',
  customer_id: 'CUST123456',
  token_expiry: '2026-01-01',
  token_reason: 'Save Card',
  token_reference: 'INV-0987'
}, intentParams.payment_intent);

Payment Result

When a card payment is completed successfully and customer_id is provided, QFPay generates a payment token and returns a token_id. The returned token_id uniquely identifies the customer’s saved payment method.

Store the returned token_id securely in your backend.Do not rely solely on browser storage or frontend state for future use.

Token Confirmation

Although confirmPayment() and confirmWalletPayment() may return a token_id, QFPay recommends using the Token Creation Notification as the authoritative confirmation that the payment token has been successfully created. Merchants should persist the token_id using the asynchronous notification whenever possible.

The Token Creation Notification uses a dedicated notification endpoint, which is different from the standard payment notification endpoint.To enable Token Creation Notifications, please contact QFPay Technical Support and provide your notification URL together with your Merchant ID and Store ID.Email: technical.support@qfpay.com

Use the synchronous SDK response to provide immediate feedback to the customer.Use the Token Creation Notification as the final source of truth for persisting the generated token_id.

Do not store raw card details collected through the Element SDK.Store only the QFPay-issued token_id.

Step 8: Confirm Payment

After the customer completes the payment, confirm the payment result using the corresponding SDK method.

Card / Apple Pay

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

Wallet Payments

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

Code	Meaning
`0000`	Success
`1111`	Apple Pay cancelled
other	Failed

When payment token creation is requested, confirmPayment() may also return the generated token_id.Token generation is currently supported only for card payments.

Step 9: Query Transaction

If the final payment result cannot be reliably determined from the client-side response, query the transaction status using the inquiry API.

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

Use Transaction Enquiry as a fallback mechanism when payment status is uncertain due to network interruptions, browser closure, or other unexpected scenarios.

Important Notes

If lang is not specified, the SDK automatically uses the browser language.

Do not place the Element container inside a <form> element. Rendering may fail.

Payment Intent expiry:

Production: 2 years
Sandbox: 7 days

Always generate signatures and create Payment Intents from your backend.Never expose your AppKey or any secret credentials in frontend code.

Do not rely solely on the frontend SDK response to determine the final transaction result.Implement Asynchronous Notifications and Transaction Enquiry to reliably confirm payment status before fulfilling an order.

Preparation

Business Scenarios

API Reference

In-Store Payments

Online Payments

Shared Endpoints

Element SDK

Integration Flow

Flow Summary

Supported Payment Methods

Integration Steps

Step 1: Load SDK

Step 2: Initialise SDK

Step 3: Create Payment Intent (Backend)

Headers

Request Parameters

Response Example

Step 4: Retrieve Payment Intent (Frontend)

Step 5: Configure Appearance (Optional)

Step 6: Render Payment UI

Enhanced Payment Interface (Wallet + Card)

Card Payment Form Only

Step 7: Initiate Payment

Card Payment

Multi-Payment Interface

Optional: Generate a Payment Token (Card Payments Only)

Token Creation Flow

Token Parameters

Example - Card Payment

Payment Result

Token Confirmation

Step 8: Confirm Payment

Card / Apple Pay

Wallet Payments

Step 9: Query Transaction

Important Notes

​Integration Flow

​Flow Summary

​Supported Payment Methods

​Integration Steps

​Step 1: Load SDK

​Step 2: Initialise SDK

​Step 3: Create Payment Intent (Backend)

​Headers

​Request Parameters

​Response Example

​Step 4: Retrieve Payment Intent (Frontend)

​Step 5: Configure Appearance (Optional)

​Step 6: Render Payment UI

​Enhanced Payment Interface (Wallet + Card)

​Card Payment Form Only

​Step 7: Initiate Payment

​Card Payment

​Multi-Payment Interface

​Optional: Generate a Payment Token (Card Payments Only)

​Token Creation Flow

​Token Parameters

​Example - Card Payment

​Payment Result

​Token Confirmation

​Step 8: Confirm Payment

​Card / Apple Pay

​Wallet Payments

​Step 9: Query Transaction

​Important Notes

Integration Flow

Flow Summary

Supported Payment Methods

Integration Steps

Step 1: Load SDK

Step 2: Initialise SDK

Step 3: Create Payment Intent (Backend)

Headers

Request Parameters

Response Example

Step 4: Retrieve Payment Intent (Frontend)

Step 5: Configure Appearance (Optional)

Step 6: Render Payment UI

Enhanced Payment Interface (Wallet + Card)

Card Payment Form Only

Step 7: Initiate Payment

Card Payment

Multi-Payment Interface

Optional: Generate a Payment Token (Card Payments Only)

Token Creation Flow

Token Parameters

Example - Card Payment

Payment Result

Token Confirmation

Step 8: Confirm Payment

Card / Apple Pay

Wallet Payments

Step 9: Query Transaction

Important Notes