Transaction Enquiry

After making a payment, refund, or cancellation request, merchants can use the transaction enquiry API to retrieve the latest transaction status. This API supports querying by:

syssn (QFPay transaction number)
out_trade_no (merchant-side order number)
start_time / end_time (time-based filtering)

If querying a refund transaction, the response will also return origssn, which refers to the original transaction’s syssn.

HTTP Request

Endpoint: /trade/v1/query
Method: POST

Request Headers

HTTP

Content-Type: application/x-www-form-urlencoded
X-QF-APPCODE: <your-app-code>
X-QF-SIGN: <signature>

Request Parameters

Full details are documented in Common API Request Format. Key parameters include:

Parameter	Type	Required	Description
`mchid`	String(16)	Conditional	Required if assigned to the merchant.
`syssn`	String(128)	No	QFPay transaction number(s), comma-separated.
`out_trade_no`	String(128)	No	Merchant order number(s), comma-separated.
`pay_type`	String(6)	No	Payment type(s), comma-separated.
`respcd`	String(4)	No	Filter by specific response code (e.g. `0000`).
`start_time`	String(20)	No	Format: `YYYY-MM-DD hh:mm:ss`. Required for cross-month queries.
`end_time`	String(20)	No	Format: `YYYY-MM-DD hh:mm:ss`. Required for cross-month queries.
`page`	Integer	No	Default = 1.
`page_size`	Integer	No	Default = 10. Max = 100.

For cross-month queries, start_time and end_time are required.

Example Request Body

Form Example

mchid=<merchant-id>&syssn=<qfpay-tx-id>&start_time=2022-12-01 00:00:00&end_time=2022-12-01 23:59:59

Sample Code (Multi-language)

import hashlib
import requests

environment = 'https://test-openapi-hk.qfapi.com'
app_code = 'D5589D2A1F2E42A9A60C37**********'
client_key = '0E32A59A8B454940A2FF39**********'

def make_req_sign(data, key):
    keys = sorted(data.keys())
    parts = []
    for k in keys:
        parts.append(f"{k}={data[k]}")
    unsign_str = ("&".join(parts) + key).encode("utf-8")
    return hashlib.md5(unsign_str).hexdigest().upper()

data = {
    'mchid': 'ZaMVg*****',
    'syssn': '20191227000200020061752831'
}

sign = make_req_sign(data, client_key)

r = requests.post(
    environment + "/trade/v1/query",
    data=data,
    headers={
        'X-QF-APPCODE': app_code,
        'X-QF-SIGN': sign
    }
)

print(sign)
print(r.json())

import java.util.HashMap;
import java.util.Map;

public class Enquiry {
    public static void main(String[] args) {
        String appcode = "D5589D2A1F2E42A9A60C37**********";
        String key = "0E32A59A8B454940A2FF39*********";
        String mchid = "ZaMVg*****";

        String syssn = "20191227000300020061662295";

        Map<String, String> params = new HashMap<>();
        params.put("mchid", mchid);
        params.put("syssn", syssn);

        String data = QFPayUtils.getDataString(params);
        String md5Sum = QFPayUtils.getMd5Value(data + key);

        String url = "https://test-openapi-hk.qfapi.com";
        String resp = Requests.sendPostRequest(url + "/trade/v1/query", data, appcode, md5Sum);
        System.out.println(resp);
    }
}

const crypto = require('crypto');
const request = require('request');

const environment = 'https://test-openapi-hk.qfapi.com';
const app_code = 'D5589D2A1F2E42A9A60C37**********';
const client_key = '0E32A59A8B454940A2FF39**********';

const payload = {
  syssn: '20191231000300020063521806',
  start_time: '2019-12-27 00:00:00',
  end_time: '2019-12-31 23:59:59',
  mchid: 'ZaMVg*****'
};

const ordered = {};
Object.keys(payload).sort().forEach(k => ordered[k] = payload[k]);

const str = Object.keys(ordered)
  .map(k => `${k}=${ordered[k]}`)
  .join('&') + client_key;

const sign = crypto.createHash('md5')
  .update(str)
  .digest('hex')
  .toUpperCase();

request({
  uri: environment + "/trade/v1/query",
  headers: { 'X-QF-APPCODE': app_code, 'X-QF-SIGN': sign },
  method: "POST",
  form: payload
}, (error, response, body) => {
  console.log(body);
});

<?php
$url = 'https://test-openapi-hk.qfapi.com';
$api_type = '/trade/v1/query';

$app_code = 'FF2FF74F2F2E42769A4A73*********';
$app_key  = '7BE791E0FD2E48E6926043B*********';

$fields = array(
  'syssn' => '20200311066100020000977841'
);

ksort($fields);

$fields_string = '';
foreach ($fields as $k => $v) {
  $fields_string .= $k.'='.urlencode($v).'&';
}
$fields_string = rtrim($fields_string, '&');

$sign = strtoupper(md5($fields_string . $app_key));

$header = array(
  'X-QF-APPCODE: ' . $app_code,
  'X-QF-SIGN: ' . $sign
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . $api_type);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields_string);

$output = curl_exec($ch);
curl_close($ch);

echo $output;
?>

Sample Response

JSON

{
  "respcd": "0000",
  "resperr": "Request successful",
  "data": [
    {
      "syssn": "20230423000200020088888888",
      "out_trade_no": "YOUR_ORDER_001",
      "txamt": "100",
      "txcurrcd": "HKD",
      "respcd": "0000",
      "errmsg": "success",
      "pay_type": "801107",
	  "note": "reference txn note",
      "order_type": "payment",
      "txdtm": "2023-04-23 12:00:00",
      "sysdtm": "2023-04-23 12:00:03",
      "cancel": "0",
      "cash_fee": "100",
      "cash_fee_type": "HKD"
    }
  ]
}

Preparation

Business Scenarios

API Reference

In-Store Payments

Online Payments

Shared Endpoints

HTTP Request

Request Headers

Request Parameters

Example Request Body

Sample Code (Multi-language)

Sample Response

​HTTP Request

​Request Headers

​Request Parameters

​Example Request Body

​Sample Code (Multi-language)

​Sample Response

HTTP Request

Request Headers

Request Parameters

Example Request Body

Sample Code (Multi-language)

Sample Response