> ## 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.

# Web 支付（線上網頁付款）

> 本文件說明如何透過 API 整合微信、支付寶、PayMe、銀聯等 Web 支付流程（顯示 QR Code 或跳轉支付頁）。

## 簡介

Web 支付允許用戶在商戶網站中使用第三方電子錢包完成付款。

依支付方式不同，用戶可能：

* 掃描 QR Code 完成付款（桌面網站常見）
* 或跳轉至對應錢包頁面完成支付

支付完成後，可透過 `return_url` 將用戶導回商戶頁面。

目前支援之錢包支付將以港幣（HKD）向用戶扣款，QFPay 亦以港幣結算給商戶。

***

## API 端點與方法

```http 建立 Web 支付交易 theme={null}
POST /trade/v1/payment
```

***

## 支援支付類型（香港環境）

| PayType  | 支付方式         |
| -------- | ------------ |
| `800201` | 微信 Web 掃碼支付  |
| `801514` | 支付寶 Web 支付   |
| `800714` | 銀聯雲閃付 PC-Web |
| `805814` | PayMe Web 支付 |

***

## 請求參數

| 參數名稱    | 參數編碼           | 必填 | 類型          | 說明                                        |
| ------- | -------------- | -- | ----------- | ----------------------------------------- |
| 訂單金額    | `txamt`        | 是  | Int(11)     | 最小幣值單位（100 = 1 元）。**建議大於 200** 以降低風控拒付機率。 |
| 交易幣別    | `txcurrcd`     | 是  | String(3)   | 三位貨幣代碼。                                   |
| 支付方式    | `pay_type`     | 是  | String(6)   | 對應支付方式之 PayType。                          |
| 商戶訂單號   | `out_trade_no` | 是  | String(128) | Merchant Order Number，單一商戶下必須唯一。          |
| 交易時間    | `txdtm`        | 是  | String(20)  | 格式：`YYYY-MM-DD hh:mm:ss`                  |
| 二維碼過期時間 | `expired_time` | 否  | String(3)   | 單位分鐘，預設 30，範圍 5–120（僅限掃碼模式）。              |
| 商品名稱    | `goods_name`   | 否  | String(64)  | 最多 20 字元，僅限英數與 UTF-8 中文，不可含特殊符號。          |
| 子商戶號    | `mchid`        | 否  | String(16)  | 由 QFPay 分配，用於識別子商戶。                       |
| 設備識別碼   | `udid`         | 否  | String(40)  | 顯示於後台交易管理頁。                               |
| 返回網址    | `return_url`   | 否  | String(512) | 支付完成後導向頁面。                                |

***

## 回應參數

| 參數名稱      | 參數編碼           | 類型          | 說明                                         |
| --------- | -------------- | ----------- | ------------------------------------------ |
| 支付方式      | `pay_type`     | String(6)   | 對應支付方式。                                    |
| 系統交易時間    | `sysdtm`       | String(20)  | 用作清算依據的系統時間。                               |
| 商戶交易時間    | `txdtm`        | String(20)  | 商戶原始提交時間。                                  |
| 交易金額      | `txamt`        | Int(11)     | 訂單金額。                                      |
| 商戶訂單號     | `out_trade_no` | String(128) | Merchant Order Number。                     |
| QFPay 訂單號 | `syssn`        | String(40)  | QFPay Transaction ID。                      |
| 回應碼       | `respcd`       | String(4)   | `0000` = 成功建立交易；`1143/1145` = 狀態未確定；其他為失敗。 |
| 回應說明      | `resperr`      | String(128) | 錯誤或處理說明。                                   |
| 附加訊息      | `respmsg`      | String(128) | 補充回傳資訊。                                    |
| 支付網址      | `pay_url`      | String(512) | 用於生成 QR Code 或跳轉至支付頁面。                     |

***

## 交易流程說明

1. 商戶呼叫 `/trade/v1/payment`
2. 系統回傳 `pay_url`
3. 商戶：
   * 產生 QR Code 顯示給用戶掃描\
     或
   * 導向該 URL 進行支付
4. 用戶完成付款
5. 系統透過 Webhook 傳送最終交易結果

***

## 重要注意事項

<Warning>
  `respcd = 0000` 僅代表交易建立成功。\
  最終支付結果必須透過 Webhook 或交易查詢 API 確認。
</Warning>

<Note>
  當回應碼為 `1143` 或 `1145` 時，代表交易狀態未確定。\
  商戶需主動查詢交易結果。
</Note>

***

## 小結

* 適用於網站掃碼或 Web 跳轉支付場景
* 回傳 `pay_url` 供產生 QR Code 或跳轉
* 建議實作 Webhook 與交易查詢 API
* 建議測試 QR Code 過期與回跳流程