當商戶發起付款、退款或撤銷後，建議透過本查詢 API 確認交易最終狀態。
此接口適用於：
- 交易處於處理中（如 1143 / 1145）
- 避免重複請求
- 對帳與補償流程
- 系統異常後的狀態確認
查詢方式
支援以下查詢條件：
- 使用 QFPay 訂單號
syssn
- 使用商戶訂單號
out_trade_no
- 使用時間區間
start_time + end_time
若為退款交易，回應中將包含 origssn，對應原始付款交易的 syssn。
HTTP 請求
Endpoint
Content-Type: application/x-www-form-urlencoded
X-QF-APPCODE: <your-app-code>
X-QF-SIGN: <signature>
請求參數
完整格式請參考：
通用 API 請求格式
以下為交易查詢主要參數：
| 參數 | 類型 | 是否必填 | 說明 |
|---|
mchid | String(16) | 視情況 | 若商戶開通時提供 mchid，則必填；否則不可傳入 |
syssn | String(128) | 否 | QFPay 訂單號，可多筆，使用逗號分隔 |
out_trade_no | String(128) | 否 | 商戶訂單號，可多筆，使用逗號分隔 |
pay_type | String(6) | 否 | 支付類型，可多筆，使用逗號分隔 |
respcd | String(4) | 否 | 指定篩選特定狀態碼 |
start_time | String(20) | 否 | 開始時間，格式：YYYY-MM-DD HH:mm:ss |
end_time | String(20) | 否 | 結束時間，格式：YYYY-MM-DD HH:mm:ss |
page | Integer | 否 | 預設 1 |
page_size | Integer | 否 | 預設 10，最大 100 |
查詢規則說明
至少需提供以下其中一種條件：
syssnout_trade_no- 或完整時間區間（
start_time + end_time）
程式碼範例
import hashlib
import requests
environment = 'https://test-openapi-hk.qfapi.com'
app_code = 'YOUR_APP_CODE'
client_key = 'YOUR_CLIENT_KEY'
def make_sign(data, key):
ordered = sorted(data.items())
sign_str = "&".join(f"{k}={v}" for k, v in ordered) + key
return hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()
payload = {
"syssn": "20191227000200020061752831"
}
headers = {
"X-QF-APPCODE": app_code,
"X-QF-SIGN": make_sign(payload, client_key)
}
response = requests.post(
environment + "/trade/v1/query",
data=payload,
headers=headers
)
print(response.json())
const crypto = require("crypto");
const request = require("request");
const environment = "https://test-openapi-hk.qfapi.com";
const app_code = "YOUR_APP_CODE";
const client_key = "YOUR_CLIENT_KEY";
const payload = {
syssn: "20191231000300020063521806"
};
const sorted = Object.keys(payload)
.sort()
.map(k => `${k}=${payload[k]}`)
.join("&");
const sign = crypto
.createHash("md5")
.update(sorted + client_key)
.digest("hex")
.toUpperCase();
request({
uri: environment + "/trade/v1/query",
method: "POST",
headers: {
"X-QF-APPCODE": app_code,
"X-QF-SIGN": sign
},
form: payload
}, function(error, response, body) {
console.log(body);
});
回應欄位
詳細欄位請參考：
通用 API 回應格式
以下為交易查詢常見欄位：
| 欄位 | 類型 | 說明 |
|---|
syssn | String | QFPay 交易編號 |
out_trade_no | String | 商戶交易編號 |
txamt | Integer | 金額（單位：分） |
txcurrcd | String | 幣別代碼 |
respcd | String | 交易結果代碼 |
errmsg | String | 交易結果說明 |
order_type | String | payment 或 refund |
pay_type | String | 支付方式代碼 |
cancel | String | 撤銷 / 退款標記 |
cash_fee | String | 實際支付金額 |
cash_fee_type | String | 支付幣別 |
cash_refund_fee | String | 實際退款金額 |
cash_refund_fee_type | String | 退款幣別 |
exchange_rate | String | 匯率（跨幣交易時） |
sysdtm | String | QFPay 系統時間 |
txdtm | String | 商戶交易時間 |
chnlsn | String | 通道交易號 |
origssn | String | 原始交易號（僅退款時返回） |
回應範例
{
"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"
}
]
}
整合建議
- 在收到 1143 / 1145 等處理中狀態時，請使用本查詢 API 確認最終結果。
- 避免在未知狀態下重複發送支付請求。
- 對帳流程應以
syssn 作為唯一交易識別。
- 建議實作延遲查詢機制（例如 3–5 秒後再查詢）。
