跳轉到主要內容
Wechat H5
微信 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"
  }
}

​
回應參數

參數說明
syssnQFPay Transaction ID
respcdReturn Code（0000 = 交易建立成功）
sysdtmSystem 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 僅影響前端導向，不代表交易成功

​
交易生命週期說明

  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 為準