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

# 微信小程式支付

> 本文件說明如何整合微信小程式支付（Mini Program Payment），包含 openid 取得流程與支付參數構造。

<Frame>
  <img src="https://mintcdn.com/qfpay-8e347952/0qBGs20OGxD96olb/images/online-shop/wechat_mp_process.jpg?fit=max&auto=format&n=0qBGs20OGxD96olb&q=85&s=ca47f06734e71ecc655af2aee9d53c8d" alt="Wechat Mp Process" width="1362" height="780" data-path="images/online-shop/wechat_mp_process.jpg" />

  微信小程式支付適用於 **微信小程式（Mini Program）內部場景**。\
  商戶透過 QFPay API 建立交易後，將回傳的 `pay_params` 傳入 `wx.requestPayment` 以喚起微信支付模組。
</Frame>

***

# 整體流程

1. 完成微信實名認證
2. 透過小程式取得 `openid`
3. 呼叫 `/trade/v1/payment`
4. 取得 `pay_params`
5. 呼叫 `wx.requestPayment`
6. 透過 Webhook 或查詢 API 確認最終結果

***

# Step 1：微信實名認證

商戶必須於微信官方平台完成身份驗證後，方可使用微信支付功能。

官方文件：\
[https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/login/auth.code2Session.html](https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/login/auth.code2Session.html)

***

# Step 2：取得 openid

完成實名認證後，透過小程式登入流程取得使用者 `openid`。

通常透過 `wx.login()` 取得 `code`，再呼叫微信後端 API 換取 `openid`。

***

# Step 3：建立交易

## Endpoint

```http Create Mini Program Payment theme={null}
POST /trade/v1/payment
```

**PayType：** `800213`

***

## Request Headers

| Header         | 必填 | 說明                |
| -------------- | -- | ----------------- |
| `X-QF-APPCODE` | 是  | QFPay 分配之 AppCode |
| `X-QF-SIGN`    | 是  | 依簽名規則生成           |

***

## 請求參數

| 參數             | 必填 | 說明                                      |
| -------------- | -- | --------------------------------------- |
| `sub_openid`   | 是  | 使用者 openid                              |
| `out_trade_no` | 是  | Merchant Order Number（商戶訂單號，必須唯一）       |
| `txamt`        | 是  | 金額（最小幣值單位，例如 100 = 1 元）                 |
| `txcurrcd`     | 是  | 三位貨幣代碼                                  |
| `txdtm`        | 是  | Transaction Time（`YYYY-MM-DD hh:mm:ss`） |
| `expired_time` | 否  | 訂單過期時間（5–120 分鐘）                        |
| `limit_pay`    | 否  | 設為 `no_credit` 可禁止信用卡（僅限中國大陸）           |
| `extend_info`  | 否  | 實名資訊（僅限中國大陸公民）                          |

### extend\_info 範例

```json Real-name Example theme={null}
{
  "user_creid": "430067798868676871",
  "user_truename": "\\u5c0f\\u6797"
}
```

***

## Node.js 呼叫範例

```javascript Mini Program API Call Example theme={null}
qfPayOpenAPI: function () {
  let app_code = '******';
  let client_key = '******';
  let environment = 'https://test-openapi-hk.qfapi.com/trade/v1/payment';

  let payload = {
    txamt: 100,
    txcurrcd: 'SGD',
    pay_type: '800213',
    out_trade_no: '0123456789',
    txdtm: '2020-07-03 03:14:29',
    sub_openid: 'oS80_5dxekECAOlVBeQFk34q123s'
  };

  var ordered = {};
  Object.keys(payload).sort().forEach(function(key) {
    ordered[key] = payload[key];
  });

  var str = [];
  for (var p in ordered) {
    str.push(p + "=" + ordered[p]);
  }

  var signature = utilMd5.hexMD5(str.join("&") + client_key).toUpperCase();

  wx.request({
    url: environment,
    data: payload,
    method: 'POST',
    header: {
      'X-QF-APPCODE': app_code,
      'X-QF-SIGN': signature,
      'content-Type': 'application/x-www-form-urlencoded'
    },
    success: (res) => {
      if (res.statusCode == 200) {
        this.weChatPayment(res);
      }
    }
  })
}
```

***

## 回應參數（重點）

| 參數           | 說明                         |
| ------------ | -------------------------- |
| `syssn`      | QFPay Transaction ID       |
| `respcd`     | Return Code（0000 = 成功建立交易） |
| `sysdtm`     | System Time                |
| `pay_params` | 小程式支付所需參數                  |

***

## pay\_params 結構

| 欄位          | 說明         |
| ----------- | ---------- |
| `appId`     | 小程式 AppID  |
| `timeStamp` | 時間戳        |
| `nonceStr`  | 隨機字串       |
| `package`   | prepay\_id |
| `signType`  | 簽名方式       |
| `paySign`   | 簽名值        |

***

# Step 4：喚起支付模組

```javascript wx.requestPayment Example theme={null}
weChatPayment: function(res) {
  wx.requestPayment({
    timeStamp: res.data.pay_params.timeStamp,
    nonceStr: res.data.pay_params.nonceStr,
    package: res.data.pay_params.package,
    signType: res.data.pay_params.signType,
    paySign: res.data.pay_params.paySign,
    success: function(res){},
    fail: function(res){},
    complete: function(res){}
  })
}
```

<Warning>
  `respcd = 0000` 僅代表交易建立成功。\
  最終支付結果必須透過：

  * Webhook 非同步通知\
    或
  * 交易查詢 API 確認。
</Warning>

***

# 微信小程式樣板

您可下載範例樣板快速開始：

QFPay 微信小程式樣板\
/static/files/qfpay\_mini\_program\_payments\_boilerplate.zip

***

## 設定步驟

1. 向 QFPay 註冊並綁定您的微信 AppID
2. 登入 [https://mp.weixin.qq.com](https://mp.weixin.qq.com)
3. 將以下網域加入 request 合法網域白名單：

```text Allowed Domain Example theme={null}
https://test-openapi-hk.qfapi.com
```

4. 將樣板專案部署至小程式開發環境
5. 使用雲函式 `getUserOpenID` 取得 openid
6. 呼叫支付 API

***

## 小結

* 僅適用於微信小程式內部場景
* 必須先取得 openid
* API 成功僅代表交易建立
* 最終狀態請依 Webhook 或查詢 API 為準