FPS App-to-App Integration

This guide explains how a merchant mobile app or H5 page can launch supported bank apps to complete FPS App-to-App payments. QFPay provides payment parameters via API. Your application then opens the user’s banking app using platform-specific methods. After payment, the result is returned via callback or backend verification. Android and iOS platforms are supported.

Integration Overview

Choose the flow that matches your application architecture:

Platform	Flow Type	Usage Scenario	Launch Method
Android	Native App	App directly triggers FPS payment	`Intent` to bank app
Android	H5 to App	WebView triggers FPS payment	JSBridge + `Intent`
iOS	Native App	App directly triggers FPS payment	`UIActivityViewController`
iOS	H5 to App	WKWebView triggers FPS payment	WKWebView + JSBridge

For all flows:

Retrieve payment parameters via API
Launch the FPS bank app
Receive callback or verify payment status

1. Retrieve Payment Parameters

Endpoint POST /trade/v1/payment PayType: 802010

Request Parameters

Parameter	Required	Type	Description
`pay_type`	Yes	String	Fixed value `802010`
`txamt`	Yes	Int	Amount in cents (100 = HKD 1.00)
`txdtm`	Yes	String	Format: `YYYY-MM-DD hh:mm:ss`
`out_trade_no`	Yes	String	Unique merchant order reference
…	—	—	See Common Parameters

If your FPS integration is via HSBC direct channel, you must obtain a dedicated SSL certificate matching your merchant legal name.This is required for:• secure callbacks (Universal Links / HTTPS redirects)
• HSBC certification & production onboardingSee the FPS e-Cert setup guide for details.

Response Parameters

Name	Description
Common Response Fields	See response format documentation
`pay_params`	URL used to launch the FPS payment app

2. Android FPS Payment Flow

2.1 Native App-to-App Flow

This flow launches the banking app directly using an Android Intent.

Retrieve pay_params from API
Launch bank app using Intent
Receive result via onActivityResult
Verify final status via backend

Android Example

int REQUEST_CODE = 100;
String payUrl = "PAYMENT_URL_FROM_API";

Intent intent = new Intent("hk.com.hkicl");
intent.putExtra("url", payUrl);

startActivityForResult(intent, REQUEST_CODE);

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            // Payment initiated
        } else if (resultCode == RESULT_CANCELED) {
            // User cancelled or failed
        }
    }
}

2.2 Android H5-to-App (WebView)

Used when an H5 page inside WebView launches the FPS app. Flow

Enable JavaScript in WebView
Register JS bridge
H5 sends payment URL to Android
Android launches bank app
Return result to H5
Verify payment via backend

H5 example:

AndroidBridge.handleMessage(JSON.stringify({
  url: "PAYMENT_URL_FROM_API"
}));

3. iOS FPS Payment Flow

3.1 Native App-to-App Flow

iOS uses UIActivityViewController and App Extensions to launch bank apps. Flow

Retrieve payment URL
Launch bank app via extension
User completes payment
App receives Universal Link callback
Verify status via backend

Key Steps

• Create NSExtensionItem
• Package payment URL & callback URL
• Use type identifier: hk.com.hkicl
• Present UIActivityViewController

let paymentPayload = [
    "URL": paymentURL,
    "callback": "https://your-domain.com/callback"
]

let itemProvider = NSItemProvider(
    item: paymentPayload as NSDictionary,
    typeIdentifier: "hk.com.hkicl"
)

let extensionItem = NSExtensionItem()
extensionItem.attachments = [itemProvider]

let activityVC = UIActivityViewController(
    activityItems: [extensionItem],
    applicationActivities: nil
)

present(activityVC, animated: true)

3.2 iOS H5-to-App via WKWebView

Used when FPS payment is triggered from an H5 page. Flow

H5 retrieves payment URL
H5 calls native app via JSBridge
Native launches bank app
Native returns result to H5
Backend verifies final payment

Bridge call example:

window.webkit.messageHandlers.NativeBridge.postMessage({
  action: "FPSH5CallApp",
  params: { paymentRequestURL: "PAYMENT_URL_FROM_API" },
  callbackId: "callback_123"
});

Error Handling & Fallbacks

Result Codes

Code	Meaning
RESULT_OK	Payment app launched successfully
RESULT_CANCELED	Cancelled, failed, or timeout

Always verify payment using your backend order query.

If FPS App Is Not Installed

If no supported bank app is available: • show an error message
• provide fallback QR payment
• allow retry

Callback Failure

If callback or redirect fails: • inform user payment is verifying
• re-query backend after 3–5 seconds
• display loading or retry option

Demo Downloads

Platform	Flow
Android	Native & WebView
iOS	Native (Obj-C)
iOS	Native (Swift)
iOS	JSBridge

Preparation

Business Scenarios

API Reference

In-Store Payments

Online Payments

Shared Endpoints

Integration Overview

1. Retrieve Payment Parameters

Request Parameters

Response Parameters

2. Android FPS Payment Flow

2.1 Native App-to-App Flow

2.2 Android H5-to-App (WebView)

3. iOS FPS Payment Flow

3.1 Native App-to-App Flow

Key Steps

3.2 iOS H5-to-App via WKWebView

Error Handling & Fallbacks

Result Codes

If FPS App Is Not Installed

Callback Failure

Demo Downloads

​Integration Overview

​1. Retrieve Payment Parameters

​Request Parameters

​Response Parameters

​2. Android FPS Payment Flow

​2.1 Native App-to-App Flow

​2.2 Android H5-to-App (WebView)

​3. iOS FPS Payment Flow

​3.1 Native App-to-App Flow

​Key Steps

​3.2 iOS H5-to-App via WKWebView

​Error Handling & Fallbacks

​Result Codes

​If FPS App Is Not Installed

​Callback Failure

​Demo Downloads

Integration Overview

1. Retrieve Payment Parameters

Request Parameters

Response Parameters

2. Android FPS Payment Flow

2.1 Native App-to-App Flow

2.2 Android H5-to-App (WebView)

3. iOS FPS Payment Flow

3.1 Native App-to-App Flow

Key Steps

3.2 iOS H5-to-App via WKWebView

Error Handling & Fallbacks

Result Codes

If FPS App Is Not Installed

Callback Failure

Demo Downloads