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
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
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())
Sample Response
{
"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",
"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"
}
]
}
