當商戶發起付款、退款或撤銷後，建議透過本查詢 API 確認交易最終狀態。此接口適用於：

交易處於處理中（如 1143 / 1145）
避免重複請求
對帳與補償流程
系統異常後的狀態確認

查詢方式

支援以下查詢條件：

使用 QFPay 訂單號 syssn
使用商戶訂單號 out_trade_no
使用時間區間 start_time + end_time

若為退款交易，回應中將包含 origssn，對應原始付款交易的 syssn。

HTTP 請求

Endpoint

TEXT

POST /trade/v1/query

Headers

HTTP

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

查詢規則說明

至少需提供以下其中一種條件：

syssn
out_trade_no
或完整時間區間（start_time + end_time）

跨月份查詢必須提供時間區間。

程式碼範例

Python

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

JavaScript

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	原始交易號（僅退款時返回）
`note`	String	交易備注（有值時返回）

回應範例

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": "sample note for payment",
      "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 秒後再查詢）。

​查詢方式

​HTTP 請求

​Endpoint

​Headers

​請求參數

​查詢規則說明

​程式碼範例

​回應欄位

​回應範例

​整合建議

查詢方式

HTTP 請求

Endpoint

Headers

請求參數

查詢規則說明

程式碼範例

回應欄位

回應範例

整合建議