當商戶發起付款、退款或撤銷後，建議透過本查詢 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	原始交易號（僅退款時返回）

回應範例

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",
      "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 秒後再查詢）。

準備

API 參考文件

實體店支付

線上支付

共用端點

交易查詢

查詢方式

HTTP 請求

Endpoint

Headers

請求參數

查詢規則說明

程式碼範例

回應欄位

回應範例

整合建議

準備

API 參考文件

實體店支付

線上支付

共用端點

Documentation Index

​查詢方式

​HTTP 請求

​Endpoint

​Headers

​請求參數

​查詢規則說明

​程式碼範例

​回應欄位

​回應範例

​整合建議

查詢方式

HTTP 請求

Endpoint

Headers

請求參數

查詢規則說明

程式碼範例

回應欄位

回應範例

整合建議