跳轉到主要內容
本頁說明如何使用「沖正（reversal）API」撤銷一筆尚未完成的交易。沖正不是退款：若原始交易已成功（respcd=0000），請改用 退款 API。
沖正（reversal）不是退款。只有當原始交易尚未成功完成時，才能發起沖正。

​
支援場景

目前僅以下支付場景支援 /trade/v1/reversal。通常用於商戶已建立訂單，但消費者尚未完成付款（例如正掃後未付款）等未完成狀態。

​
支援的支付場景及 PayType

支付寶正掃（MPM）
  • 800101：支付寶跨境線下掃碼支付
  • 801501：支付寶線上掃碼支付（香港商戶）
微信支付正掃（MPM）
  • 800201：微信掃碼支付
支付寶反掃（CPM）
  • 800108：支付寶跨境反掃支付
如需對其他錢包或模式進行交易取消，請參考本文下方的「Reversal vs Close」或聯絡 QFPay 技術支援取得整合建議。

​
API 端點

  • Endpoint：/trade/v1/reversal
  • 方法：POST
沖正成功通常回應 respcd=0000。若原始交易已成功完成（付款回應為 respcd=0000），則無法沖正，請改用退款。

​
請求參數

參數名稱類型必填說明
mchidString(16)否QFPay 商戶號（僅部分代理商／特定配置需要）
syssnString(40)是*QFPay 交易號（付款或退款皆可能存在；此處指「要被沖正的那筆交易」）
out_trade_noString(128)是*商戶端交易單號（要被沖正的那筆交易）
txamtInt(11)是交易金額（單位：分）。建議金額 > 200 以避免風控
txdtmString(20)是原交易時間，格式：YYYY-MM-DD HH:mm:ss
udidString(40)否裝置唯一 ID（用於追蹤交易設備）
syssn 與 out_trade_no 至少提供其中一個。

​
回應參數

參數名稱類型說明
syssnString此次沖正動作的 QFPay 交易號
orig_syssnString原始（被沖正）交易的 QFPay 交易號
txamtInt沖正金額（單位：分）
txcurrcdString(3)幣別代碼（例如 HKD）
txdtmString原始交易時間
sysdtmStringQFPay 系統處理時間
chnlsnString錢包端交易號（若未產生則可能為空）
respcdString(4)回應代碼（0000=成功；1143/1145=處理中；其他=失敗）
resperrString結果訊息
respmsgString補充說明（如有）

​
程式碼範例

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: dict, key: str) -> str:
    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 = {
    "mchid": "MNxMp11FV35qQN",
    "txamt": "2500",
    "out_trade_no": "4MDGEJ7L496LAAU1V1HBY9HMOGWZWLXQ",
    "txdtm": "2020-03-05 16:50:30"
    # "syssn": "20200305066100020000977812"  # syssn / out_trade_no 擇一即可
}

headers = {
    "X-QF-APPCODE": app_code,
    "X-QF-SIGN": make_sign(payload, client_key)
}

r = requests.post(environment + "/trade/v1/reversal", data=payload, headers=headers)
print(r.json())

​
回應範例

JSON
{
  "surcharge_fee": "0",
  "resperr": "success",
  "txdtm": "2020-03-05 16:50:30",
  "syssn": "20200305066100020000977814",
  "sysdtm": "2020-03-05 16:54:38",
  "txcurrcd": "EUR",
  "respmsg": "",
  "chnlsn2": "",
  "cardcd": "",
  "udid": "qiantai2",
  "txamt": "2500",
  "orig_syssn": "20200305066100020000977813",
  "surcharge_rate": "0",
  "respcd": "0000",
  "chnlsn": ""
}

​
補充說明

  • 沖正不代表一定「不會扣款」。請務必搭配 交易查詢 API 驗證最終結果。
  • 沖正僅適用於未完成交易。對已成功的交易請使用退款。
  • 若回應為 respcd=1143 或 1145，代表處理中，請延遲後重試查詢直到取得最終狀態。

​
Reversal（沖正）vs Close（關閉訂單）

部分錢包在「取消未完成交易」時會使用 /trade/v1/close（關閉訂單）取代 /trade/v1/reversal。

​
典型支援範圍（示例）

微信支付反掃（CPM）
  • 800008：微信反掃（聚合）
  • 800208：微信反掃
  • 801008：微信香港反掃（適用於向微信香港申請的商戶）
Endpoint：/trade/v1/close
方法：GET
實際支援範圍可能因商戶配置與渠道而異。如需確認你方可用的取消方式，請聯絡技術支援。

​
Close 請求參數（摘要）

參數名稱必填類型說明
mchid否String(16)商戶號（視配置）
syssn是*String(40)QFPay 交易號
out_trade_no是*String(128)商戶訂單號
txamt是Int(11)金額（分）
txdtm是String(20)YYYY-MM-DD HH:mm:ss
udid否String(40)裝置識別碼
syssn 與 out_trade_no 至少提供其中一個。

​
Close 回應參數（摘要）

參數名稱類型說明
orig_syssnString(40)原始交易號
syssnString(40)關單交易號
out_trade_noString(128)商戶訂單號
txamtInt(11)金額（分）
txcurrcdString(3)幣別
txdtmString(20)原交易時間
sysdtmString(20)系統處理時間
chnlsnString通道交易號
respcdString(4)0000=成功；1143/1145=處理中；其他=失敗
resperrString(128)結果描述
respmsgString(128)補充資訊