微信 H5 支付適用於 微信以外的瀏覽器環境（例如 Safari、Chrome、App 內嵌 WebView 等）。此模式會將使用者跳轉至微信支付頁面完成付款。

何時使用微信 H5 支付？

適用場景：

商戶行動網站（Mobile Web）
App 內嵌瀏覽器（非微信內）
第三方瀏覽器開啟的支付頁面

微信 H5 支付 不適用於微信內建瀏覽器。
若使用者在微信內開啟頁面，請改用「微信 JSAPI 支付」。

API 端點與方法

建立 H5 交易

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 結構

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"
}

參數說明

主欄位	子欄位	必填	說明
`scene_info`	—	是	場景資訊容器
—	`h5_info`	是	固定傳入
—	`type`	是	固定為 `"Wap"`
—	`wap_url`	是	商戶手機版網站網址
—	`wap_name`	是	顯示給使用者的網站名稱
`spbill_create_ip`	—	是	使用者設備的真實 IP

請確保 spbill_create_ip 為使用者設備的真實來源 IP。
若傳入伺服器 IP 或錯誤 IP，可能導致微信風控拒絕交易。

請求範例

H5 支付請求範例

{
  "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`	使用者需跳轉的微信支付網址

回應範例

H5 支付回應範例

{
  "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

原始支付網址

https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096

加入 redirect_url

加入 redirect_url 後

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 僅影響前端導向，不代表交易成功

交易生命週期說明

商戶呼叫 /trade/v1/payment
QFPay 回傳 pay_url
使用者跳轉至微信頁面完成支付
QFPay 發送 Webhook 非同步通知

respcd = 0000 僅代表交易建立成功。
最終交易結果必須透過：

Webhook 非同步通知
或
交易查詢 API 確認。

整合建議與最佳實務

請保存以下欄位以利對帳與補單：

syssn（QFPay Transaction ID）
out_trade_no（Merchant Order Number）

不應僅依賴前端跳轉結果判斷成功
若使用者中途離開頁面，請透過查詢 API 同步狀態

小結

適用於第三方瀏覽器環境
必須提供正確 scene_info
必須傳入使用者真實 IP
最終交易狀態以 Webhook / 查詢 API 為準

​何時使用微信 H5 支付？

​API 端點與方法

​請求標頭

​請求參數

​extend_info 結構

​參數說明

​請求範例

​回應參數

​回應範例

​redirect_url 使用方式

​原始 pay_url

​加入 redirect_url

​注意事項

​交易生命週期說明

​整合建議與最佳實務

​小結

何時使用微信 H5 支付？

API 端點與方法

請求標頭

請求參數

extend_info 結構

參數說明

請求範例

回應參數

回應範例

redirect_url 使用方式

原始 pay_url

加入 redirect_url

注意事項

交易生命週期說明

整合建議與最佳實務

小結