> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 線上預授權支付 API（Pre-authorisation）

> 本文件說明如何使用 QFPay 線上預授權支付 API，包含預授權建立、扣款（Capture）、解凍（Unfreeze）、退款（Refund）與通知機制。

線上預授權支付（Pre-authorisation）允許商戶**先凍結消費者帳戶中的一筆資金**，待實際提供商品或服務後，再於有效期限內進行：

* 實際扣款（Capture）
* 解凍未使用金額（Unfreeze）

此模式可降低後續扣款失敗的風險。

***

## 預授權適用場景

常見業務情境包括：

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

***

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

不同產業與渠道支援不同的最長扣款期限：

| 行業類型         | 最長 Capture 天數 |
| ------------ | ------------- |
| 一般行業         | 最多 7 天        |
| 特定行業（如酒店、租車） | 最多 28 天       |

<Note>
  實際可用天數依商戶簽約設定與支付渠道為準。\
  請於正式上線前向 QFPay 確認。
</Note>

***

## 整體流程說明

<Frame>
  ![](https://www.plantuml.com/plantuml/png/XOynJWKX441xJZ6r2HUmCDzu0HihOp61mIM1WSpE57fwTv4biJ0_eHZ8UpouxOgYLelRSYIWslKB8kr1SjVSsBq_V83tJ_0gz6owDSdV51-X2tcSUpn1m33uFzmmNx2hoIc5t-b_z8sJ48s0pN72SAnafG3MPgoEcn8KIWejhOBRhVSc2Xr5CvOhw8WZd8Qxo54xlhOExjU5AcRE_0dSs8VfpVU0M_Aw-dPKhPOV)
</Frame>

***

# 操作流程說明

## 1️⃣ 建立預授權交易

預授權交易需透過 **Payment Element（支付組件）** 完成。

此步驟：

* 凍結消費者資金
* 不會實際扣款

<Note>
  請參閱 Payment Element SDK 文件完成前端整合。
</Note>

***

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

在有效期限內，商戶可對已凍結金額進行實際扣款。

✅ 可分次扣款\
⚠ 累計金額不得超過原始預授權金額

***

### API 端點與方法

```http 預授權扣款 theme={null}
POST /trade/v1/authtrade
```

***

### 請求標頭

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

***

### 請求參數

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

***

### 回應範例

```json Capture Response Example theme={null}
{
  "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 端點與方法

```http 預授權解凍 theme={null}
POST /trade/v1/unfreeze
```

***

### 請求參數

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

***

### 回應範例

```json Unfreeze Response Example theme={null}
{
  "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

```http 退款 API theme={null}
POST /trade/v1/refund
```

請參閱 Refund API 文件了解完整參數說明。

***

# 非同步通知機制（Webhook）

當成功執行以下操作時，系統將發送 `notify_url` 通知：

| 操作          | notify\_type |
| ----------- | ------------ |
| Capture 扣款  | `payment`    |
| Unfreeze 解凍 | `unfreeze`   |
| Refund 退款   | `refund`     |

***

## 通知範例

```json Preauth Notify Example theme={null}
{
  "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"
}
```

<Warning>
  請務必驗證通知簽名，避免依賴未驗證資料更新訂單狀態。
</Warning>

***

# 最佳實務與風險提醒

<Warning>
  若未於有效期限內執行 Capture，預授權金額將自動解凍。

  如顧客取消授權或帳戶餘額變動，可能導致後續扣款失敗。
</Warning>

<Note>
  以下操作皆可透過 API 或 QFPay 商戶後台執行：

  * Capture 扣款
  * Unfreeze 解凍
  * Refund 退款
</Note>

***

## 小結

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