> ## 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.
# 微信 H5 支付（第三方瀏覽器）
> 本文件說明如何整合微信 H5 支付（非微信瀏覽器環境），包含 scene_info 設定與 redirect_url 使用方式。
微信 H5 支付適用於 **微信以外的瀏覽器環境**（例如 Safari、Chrome、App 內嵌 WebView 等）。
此模式會將使用者跳轉至微信支付頁面完成付款。
***
# 何時使用微信 H5 支付？
適用場景：
* 商戶行動網站（Mobile Web）
* App 內嵌瀏覽器（非微信內）
* 第三方瀏覽器開啟的支付頁面
微信 H5 支付 **不適用於微信內建瀏覽器**。\
若使用者在微信內開啟頁面，請改用「微信 JSAPI 支付」。
***
# API 端點與方法
```http 建立 H5 交易 theme={null}
POST /trade/v1/payment
```
**PayType：** `800212`
***
# 請求標頭
| Header | 必填 | 說明 |
| -------------- | -- | ----------------- |
| `X-QF-APPCODE` | 是 | QFPay 分配之 AppCode |
| `X-QF-SIGN` | 是 | 根據簽名規則產生之 API 簽名 |
***
# 請求參數
除公共支付參數外，必須傳入 `extend_info`。
| 參數 | 必填 | 說明 |
| -------------- | -- | --------------------------------------- |
| `out_trade_no` | 是 | Merchant Order Number（商戶訂單號，必須唯一） |
| `txamt` | 是 | 交易金額（最小幣值單位，例如 100 = 1 元） |
| `txcurrcd` | 是 | 三位貨幣代碼 |
| `txdtm` | 是 | Transaction Time（`YYYY-MM-DD hh:mm:ss`） |
| `extend_info` | 是 | H5 場景資訊 |
***
## extend\_info 結構
```json extend_info 範例 theme={null}
{
"scene_info": {
"h5_info": {
"type": "Wap",
"wap_url": "https://example.com/mobile",
"wap_name": "Example Store"
}
},
"spbill_create_ip": "203.0.113.1"
}
```
***
## 參數說明
| 主欄位 | 子欄位 | 必填 | 說明 |
| ------------------ | ---------- | -- | ----------- |
| `scene_info` | — | 是 | 場景資訊容器 |
| — | `h5_info` | 是 | 固定傳入 |
| — | `type` | 是 | 固定為 `"Wap"` |
| — | `wap_url` | 是 | 商戶手機版網站網址 |
| — | `wap_name` | 是 | 顯示給使用者的網站名稱 |
| `spbill_create_ip` | — | 是 | 使用者設備的真實 IP |
請確保 `spbill_create_ip` 為使用者設備的真實來源 IP。\
若傳入伺服器 IP 或錯誤 IP，可能導致微信風控拒絕交易。
***
# 請求範例
```json H5 支付請求範例 theme={null}
{
"pay_type": "800212",
"txamt": "100",
"txcurrcd": "HKD",
"out_trade_no": "ORDER12345",
"txdtm": "2026-03-03 18:00:00",
"extend_info": {
"scene_info": {
"h5_info": {
"type": "Wap",
"wap_url": "https://example.com/mobile",
"wap_name": "Example Store"
}
},
"spbill_create_ip": "203.0.113.1"
}
}
```
***
# 回應參數
| 參數 | 說明 |
| --------- | ---------------------------- |
| `syssn` | QFPay Transaction ID |
| `respcd` | Return Code（`0000` = 交易建立成功） |
| `sysdtm` | System Time |
| `pay_url` | 使用者需跳轉的微信支付網址 |
***
## 回應範例
```json H5 支付回應範例 theme={null}
{
"respcd": "0000",
"syssn": "20240424180500020000015704",
"sysdtm": "2024-04-24 15:19:37",
"pay_url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2016xxxx"
}
```
***
# redirect\_url 使用方式
若希望使用者支付完成後自動跳轉回商戶頁面，可在 `pay_url` 後追加 `redirect_url` 參數。
***
## 原始 pay\_url
```text 原始支付網址 theme={null}
https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096
```
***
## 加入 redirect\_url
```text 加入 redirect_url 後 theme={null}
https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.example.com
```
***
## 注意事項
* `redirect_url` 必須 URL encode
* 請實際測試完整跳轉流程
* redirect\_url 僅影響前端導向，不代表交易成功
***
# 交易生命週期說明
1. 商戶呼叫 `/trade/v1/payment`
2. QFPay 回傳 `pay_url`
3. 使用者跳轉至微信頁面完成支付
4. QFPay 發送 Webhook 非同步通知
`respcd = 0000` 僅代表交易建立成功。\
最終交易結果必須透過：
* Webhook 非同步通知\
或
* 交易查詢 API 確認。
***
# 整合建議與最佳實務
請保存以下欄位以利對帳與補單：
* `syssn`（QFPay Transaction ID）
* `out_trade_no`（Merchant Order Number）
* 不應僅依賴前端跳轉結果判斷成功
* 若使用者中途離開頁面，請透過查詢 API 同步狀態
***
## 小結
* 適用於第三方瀏覽器環境
* 必須提供正確 `scene_info`
* 必須傳入使用者真實 IP
* 最終交易狀態以 Webhook / 查詢 API 為準