跳轉到主要內容
本頁說明如何透過 /trade/v1/refund已成功的付款交易發起退款(全額或部分)。
僅當付款交易返回碼為 0000(交易成功) 時,才能進行退款操作。
若為信用卡交易,QFPay 會自動進行 Capture;同日退款申請通常會以 void 方式處理(一般無需商戶額外判斷)。
不同錢包的退款規則(例如可退款期限、是否支援部分退款)可能不同,請以實際開通配置為準。

API 端點

  • Endpoint/trade/v1/refund
  • 方法POST

HTTP Request


請求參數

參數必填類型說明
syssnString(128)欲退款的原始付款交易 QFPay 交易號
out_trade_noString(128)商戶端退款單號(退款請求的唯一識別;同一商戶帳戶下不可重複)
txamtInt(11)退款金額(單位:分)。部分錢包不支援部分退款;建議金額 > 200 以避免風控
txdtmString(20)退款請求時間,格式:YYYY-MM-DD HH:mm:ss
mchid視情況String(16)若系統有配置商戶號則必填,否則不可填寫
udidString(40)裝置 ID,用於識別交易設備
syssn 在不同 API 的語境下可能代表「付款交易號」或「退款交易號」。
退款 API 的請求中,syssn 必須填「原始付款交易」的交易號;回應中的 syssn 才是「本次退款交易」的交易號。
若未配置 mchid,請勿在請求中傳入該欄位(包含簽名字串亦不得包含)。

回應參數

參數類型說明
syssnString(40)此次退款交易所對應的 QFPay 交易號
orig_syssnString(128)原始付款交易號
txamtInt(11)退款金額(單位:分)
sysdtmString(20)系統退款時間(YYYY-MM-DD HH:mm:ss,常用作結算分界時間)
respcdString(4)0000=成功;1143/1145=處理中;其他=失敗(請參考狀態碼文件)
resperrString(128)返回訊息
cash_feeString實際支付金額(扣除折扣後)
cash_fee_typeString實際支付幣種(例如 CNY)
cash_refund_feeString實際退款金額
cash_refund_fee_typeString實際退款幣種(例如 CNY)

範例程式碼


回應示例

JSON

注意事項

  • 請確保退款金額不超過原始交易金額。
  • 部分錢包不支援部分退款,請先確認實際開通配置。
  • 各支付通道的退款有效期限不同,請以渠道規則與商戶配置為準。
  • 若退款結果為失敗(respcd0000),建議實作重試邏輯,或透過 交易查詢 API 驗證退款狀態。