跳轉到主要內容
線上預授權支付（Pre-authorisation）允許商戶先凍結消費者帳戶中的一筆資金，待實際提供商品或服務後，再於有效期限內進行：
  • 實際扣款（Capture）
  • 解凍未使用金額（Unfreeze）
此模式可降低後續扣款失敗的風險。

​
預授權適用場景

常見業務情境包括：
  • 酒店 / 住宿業：入住前凍結押金，退房後依實際消費扣款
  • 租車 / 設備租賃：取車或取件時凍結保證金
  • 電商延後出貨：下單時保留金額，出貨後再扣款
  • 訂閱 / 延期確認服務：先確認支付能力，再於服務完成後扣款
  • 可變金額交易：避免最終金額高於原始授權

​
預授權有效期限（Capture 時效）

不同產業與渠道支援不同的最長扣款期限：
行業類型最長 Capture 天數
一般行業最多 7 天
特定行業（如酒店、租車）最多 28 天
實際可用天數依商戶簽約設定與支付渠道為準。
請於正式上線前向 QFPay 確認。

​
整體流程說明

​
操作流程說明

​
1️⃣ 建立預授權交易

預授權交易需透過 Payment Element（支付組件） 完成。 此步驟：
  • 凍結消費者資金
  • 不會實際扣款
請參閱 Payment Element SDK 文件完成前端整合。

​
2️⃣ 預授權扣款（Capture）

在有效期限內，商戶可對已凍結金額進行實際扣款。 ✅ 可分次扣款
⚠ 累計金額不得超過原始預授權金額

​
API 端點與方法

預授權扣款
POST /trade/v1/authtrade

​
請求標頭

Header必填說明
X-QF-APPCODE是App Code
X-QF-SIGN是API 簽名

​
請求參數

參數必填說明
txamt是本次扣款金額（建議 > 200）
txcurrcd否扣款幣別
mchid否商戶編號（部分渠道需要）
syssn是原預授權交易的系統訂單號

​
回應範例

Capture Response Example
{
  "sysdtm": "2024-02-26 15:04:12",
  "paydtm": "2024-02-26 15:04:12",
  "txcurrcd": "HKD",
  "txdtm": "2024-02-26 07:04:11",
  "txamt": "500",
  "resperr": "交易成功",
  "respmsg": "Capture received",
  "syssn": "20240226180500020000014116",
  "orig_syssn": "20240226180500020000014079",
  "respcd": "0000"
}

​
3️⃣ 預授權金額解凍（Unfreeze）

僅限尚未被扣款之金額。 ⚠ 解凍僅可操作一次
⚠ 解凍後不可再次扣款

​
API 端點與方法

預授權解凍
POST /trade/v1/unfreeze

​
請求參數

參數必填說明
txamt是解凍金額
txdtm是解凍時間
syssn是原預授權 syssn
out_trade_no是原預授權商戶訂單號
mchid否商戶 ID（部分渠道）

​
回應範例

Unfreeze Response Example
{
  "sysdtm": "2024-02-26 17:17:05",
  "txamt": "2000",
  "resperr": "交易成功",
  "respmsg": "Void received",
  "syssn": "20240226180500020000014222",
  "orig_syssn": "20240226180500020000014220",
  "respcd": "0000"
}

​
4️⃣ 已扣款交易退款（Refund）

若已完成 Capture，需透過退款 API 進行退款。 退款對象為 Capture 產生之 syssn。

​
退款 API

退款 API
POST /trade/v1/refund
請參閱 Refund API 文件了解完整參數說明。

​
非同步通知機制（Webhook）

當成功執行以下操作時，系統將發送 notify_url 通知：
操作notify_type
Capture 扣款payment
Unfreeze 解凍unfreeze
Refund 退款refund

​
通知範例

Preauth Notify Example
{
  "status": "1",
  "pay_type": "800101",
  "sysdtm": "2020-05-14 12:32:56",
  "txcurrcd": "HKD",
  "txdtm": "2020-05-14 12:32:56",
  "txamt": "10",
  "out_trade_no": "YEPE7WTW46NVU30JW5N90H7DHD94N56B",
  "syssn": "20200514000300020093755455",
  "respcd": "0000",
  "notify_type": "payment"
}
請務必驗證通知簽名，避免依賴未驗證資料更新訂單狀態。

​
最佳實務與風險提醒

若未於有效期限內執行 Capture，預授權金額將自動解凍。如顧客取消授權或帳戶餘額變動，可能導致後續扣款失敗。
以下操作皆可透過 API 或 QFPay 商戶後台執行：
  • Capture 扣款
  • Unfreeze 解凍
  • Refund 退款

​
小結

  • 預授權適用於延後扣款或可變金額場景
  • 可分次 Capture，但不可超額
  • 解凍僅可執行一次
  • 必須實作 Webhook 與查詢 API 保障交易狀態一致