跳轉到主要內容
本頁說明如何使用「沖正(reversal)API」撤銷交易。請注意,沖正的行為依**支付場景(反掃 vs 信用卡)**而有本質上的不同:
  1. 反掃場景:僅能撤銷尚未完成的交易。若原始交易已成功(respcd=0000),請改用 退款 API
  2. 信用卡 / Apple Pay 場景:用於撤銷已經完成的卡交易。執行後會直接取消該筆交易。
對於支付寶、微信支付等錢包,沖正(reversal)不是退款。只有當原始交易尚未成功完成時,才能發起沖正。

支援場景

目前以下支付場景支援 /trade/v1/reversal。請根據你的接入場景確認對應的交易行為。

1. 反掃支付場景

通常用於商戶已建立訂單,但消費者尚未完成付款等狀態。
  • 支付寶
    • 800108:支付寶反掃支付
  • 微信支付
    • 800208:微信反掃支付
  • 銀聯雲閃付
    • 800708:銀聯雲閃付反掃支付

2. 信用卡 / Apple Pay 場景(適用於「已完成」交易)

  • 線上信用卡支付
    • 802801: Visa/Mastercard
  • Apple Pay 交易
    • 806527: Apple Pay
  • 行為說明:在此場景下,沖正的效果為**撤銷(Void)**該筆已扣款或已授權的卡交易。
如需對其他錢包或模式進行交易取消,請參考本文下方的「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(用於追蹤交易設備)
syssnout_trade_no 至少提供其中一個。

回應參數

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

程式碼範例

Python
Java
JavaScript
PHP

回應範例

JSON

補充說明

  • 沖正不代表一定「不會扣款」。請務必搭配 交易查詢 API 驗證最終結果。
  • 若回應為 respcd=11431145,代表處理中,請延遲後重試查詢直到取得最終狀態。

Reversal(沖正)vs Close(關閉訂單)

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

典型支援範圍(示例)

  • 800201:微信正掃
  • 800212:微信H5支付
  • 800701:銀聯雲閃付正掃
  • 801514:支付宝PC正掃
Endpoint/trade/v1/close
方法GET
實際支援範圍可能因商戶配置與渠道而異。如需確認你方可用的取消方式,請聯絡技術支援。

Close 請求參數(摘要)

參數名稱必填類型說明
mchidString(16)商戶號(視配置)
syssn是*String(40)QFPay 交易號
out_trade_no是*String(128)商戶訂單號
txamtInt(11)金額(分)
txdtmString(20)YYYY-MM-DD HH:mm:ss
udidString(40)裝置識別碼
syssnout_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)補充資訊