> ## 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.
# 微信 In-App 支付（App 內微信支付）
> 本文件說明如何整合微信 In-App 支付（WeChat App Payment），適用於原生 App 內透過微信 SDK 完成付款流程。
微信 In-App 支付適用於 **原生 App（iOS / Android）** 內的支付場景。\
商戶透過 QFPay API 建立交易後，將回傳的 `pay_params` 傳入微信官方 SDK，由微信 App 完成最終扣款流程。
***
## 前置條件
在整合前，商戶必須完成以下準備：
* 於 **微信開放平台** 申請並開通 App 支付能力
* 取得對應的 **AppID**
* App 完成微信平台審核並正式上架
* 已向 QFPay 開通 PayType `800210`
官方說明文件：\
[https://pay.weixin.qq.com/wiki/doc/api/wxpay/en/pay/In-AppPay/chapter6\_2.shtml#menu1](https://pay.weixin.qq.com/wiki/doc/api/wxpay/en/pay/In-AppPay/chapter6_2.shtml#menu1)
***
## 實名認證（選用功能）
商戶可選擇啟用 **微信實名認證（Real-name Verification）**。
規則說明：
* 若提交身份資料，付款人微信帳戶資訊需與資料一致
* 即使未綁定銀行卡，仍可完成付款
* 是否強制實名，依商戶與 PayType 開通狀態為準
***
## SDK 下載
請依平台下載並整合微信官方 SDK：
[https://developers.weixin.qq.com/doc/oplatform/Downloads/iOS\_Resource.html](https://developers.weixin.qq.com/doc/oplatform/Downloads/iOS_Resource.html)
***
# API 說明
## Endpoint
**POST** `/trade/v1/payment`
**PayType：** `800210`（微信 In-App 支付）
***
## 請求參數
| 參數名稱 | 參數編碼 | 必填 | 說明 |
| ------ | -------------- | --- | ------------------------- |
| 商戶 ID | `mchid` | 視情況 | 僅代理商或特定模式需要，請按實際開通狀態使用。 |
| 商戶訂單號 | `out_trade_no` | 是 | 商戶系統唯一訂單號（不可重複） |
| 交易金額 | `txamt` | 是 | 最小幣值單位，例如 100 = 1 元 |
| 交易幣別 | `txcurrcd` | 是 | 三位貨幣代碼 |
| 人民幣標記 | `rmb_tag` | 否 | 香港微信 CNY 交易需設 `rmb_tag=Y` |
| 交易時間 | `txdtm` | 是 | `YYYY-MM-DD hh:mm:ss` |
| 裝置識別碼 | `udid` | 否 | 商戶 App 裝置識別 |
| 回傳網址 | `return_url` | 否 | 部分支付場景可能需要 |
| 客戶擴展資訊 | `extend_info` | 否 | 實名認證資料（僅限中國大陸公民） |
***
### extend\_info 格式
如需提交中國大陸用戶實名資訊，請使用以下 JSON 格式。
```json Real-name Verification Example theme={null}
{
"user_creid": "430067798868676871",
"user_truename": "\u5c0f\u6797"
}
```
說明：
* `user_creid`：付款人身分證號碼
* `user_truename`：付款人真實姓名（UTF-8 或 Unicode 編碼）
***
## 請求範例
```json Request Example theme={null}
{
"goods_info": "test_app",
"goods_name": "qfpay",
"out_trade_no": "O5DNgEgL1XpvbvQSfPhN",
"pay_type": "800210",
"txamt": 10,
"txcurrcd": "HKD",
"txdtm": "2019-09-13 04:53:03",
"udid": "AA"
}
```
***
# API 回應說明
當 `respcd = 0000` 時，表示交易建立成功。\
此時尚未完成扣款，商戶必須呼叫微信 SDK 才會真正觸發付款。
***
## 回應參數
| 參數 | 說明 |
| -------------- | ------------------------------ |
| `syssn` | **QFPay Transaction ID**（系統產生） |
| `out_trade_no` | 商戶訂單號 |
| `txdtm` | 商戶交易時間 |
| `txamt` | 交易金額 |
| `sysdtm` | **System Time**（QFPay 處理時間） |
| `respcd` | **Return Code**（0000 = 成功建立交易） |
| `respmsg` | 回應訊息 |
| `resperr` | 錯誤說明 |
| `txcurrcd` | 交易貨幣 |
| `pay_params` | 提供給微信 SDK 的參數 |
***
## 回應範例
```json Response Example theme={null}
{
"sysdtm": "2019-09-13 12:53:04",
"txcurrcd": "HKD",
"pay_params": {
"package": "Sign=WXPay",
"timestamp": 1568350384,
"sign": "XwFjohEKWdkhhT4ueg7BxeDn8tT9LcqoZYdXzifTMYyDGe3/tRchpii6vWgOn21tPSaAtqo766gvifXgDEOwR+ILKN8t97r624IJlrH0EkvSUSLh9E/cga9scXGVy0jPWHM/oVvVzJIvXew79CwZFCNTSJok2KmpSm9X9oPg7PGXbqvNMHltf+YlIOsuiz391qVmFtTE5A/cpA50+06T7iW8GYsOJQTTJed75VY+aSzNo5C6ju6WSgJKpAJJ0ocl+ONtmOp6GLVBSQXaMC4PitQcebcoP2J6fFgQ+YcPwHXasCYEnn4LaFN7zT/AjGg3E3gdCx3ksGNBOazYBRVz+g==",
"partnerid": "316525492",
"appid": "wx3c6896fa9b351f2a",
"prepayid": "wx131253044253463a81dc336e1254149882",
"noncestr": "7786db42d9a245c2b1cfc717ac59376e"
},
"pay_type": "800210",
"txdtm": "2019-09-13 04:53:03",
"txamt": "10",
"resperr": "交易成功",
"out_trade_no": "O5DNgEgL1XpvbvQSfPhN",
"syssn": "20190913152100020001567741",
"respcd": "0000"
}
```
***
# 交易生命週期說明（重要）
1. 商戶呼叫 `/trade/v1/payment`
2. QFPay 回傳 `pay_params`
3. 商戶 App 呼叫微信 SDK
4. 使用者於微信完成付款
5. QFPay 透過 **Webhook 非同步通知** 回傳最終結果
`respcd = 0000` 僅代表交易建立成功。\
最終交易結果必須依賴：
* Webhook 通知\
或
* 交易查詢 API 確認
***
# 整合建議
* 必須實作 Webhook 接收最終交易狀態
* 建議保存：
* `syssn`（QFPay Transaction ID）
* `out_trade_no`
* App 不應僅依賴 SDK callback 判斷最終結果
* 若 App 被關閉，需透過查詢 API 同步狀態
***
## 小結
* 僅適用於原生 App 場景
* 必須整合微信官方 SDK
* API 成功僅代表建立交易
* 最終成功與否需以 Webhook 或查詢 API 為準