# 支付功能頁
自2025年6月26日起,不再支持新申請插件支付功能,如果要在小程序中實(shí)現(xiàn)給向第三方支付,請使用「打開半屏小程序」功能。
支付功能頁用于幫助插件完成支付,相當(dāng)于 wx.requestPayment 的功能。
自基礎(chǔ)庫版本 2.22.1 起,可以直接在插件中調(diào)用 wx.requestPluginPayment 實(shí)現(xiàn)跳轉(zhuǎn)支付;通過 functional-page-navigator 跳轉(zhuǎn)將會(huì)被廢棄。
在滿足以下條件時(shí),調(diào)用 wx.requestPluginPayment 或點(diǎn)擊 navigator 都將直接拉起支付收銀臺(tái),跳過支付功能頁:
小程序與插件綁定在同一個(gè) open 平臺(tái)賬號上
小程序與插件均為 open 賬號的同主體 / 關(guān)聯(lián)主體時(shí)。
需要注意的是:插件使用支付功能,需要進(jìn)行額外的權(quán)限申請,申請位置位于 管理后臺(tái) 的“小程序插件 -> 基本設(shè)置 -> 支付能力”設(shè)置項(xiàng)中。另外,無論是否通過申請,主體為個(gè)人小程序在使用插件時(shí),都無法正常使用插件里的支付功能。
# 調(diào)用參數(shù)
參數(shù)說明:
| 參數(shù)名 | 類型 | 必填 | 說明 |
|---|---|---|---|
| fee | Number | 是 | 需要顯示在頁面中的金額,單位為分 |
| paymentArgs | Object | 否 | 任意數(shù)據(jù),傳遞給功能頁中的響應(yīng)函數(shù) |
| currencyType | String | 否 | 需要顯示在頁面中的貨幣符號的代碼,默認(rèn)為 CNY |
currencyType 的合法值:
| 值 | 說明 | 最低版本 |
|---|---|---|
| CNY | 貨幣符號 ¥ | |
| USD | 貨幣符號 US$ | |
| JPY | 貨幣符號 J¥ | |
| EUR | 貨幣符號 € | |
| HKD | 貨幣符號 HK$ | |
| GBP | 貨幣符號 £ | |
| AUD | 貨幣符號 A$ | |
| MOP | 貨幣符號 MOP$ | |
| KRW | 貨幣符號 ? |
# 示例代碼
# wx.requestPluginPayment 方式
自基礎(chǔ)庫版本 2.22.1 起,推薦使用該方式。
<!-- plugin/components/pay.wxml -->
<button bindtap="handlePay">支付 0.01 元</button>
// plugin/components/pay.js
Component({
data: {
fee: 1, // 支付金額,單位為分
paymentArgs: 'A', // 將傳遞到功能頁函數(shù)的自定義參數(shù)
currencyType: 'USD' // 貨幣符號,頁面顯示貨幣簡寫 US$
version: 'develop', // 上線時(shí),version 應(yīng)改為 "release",并確保插件所有者小程序已經(jīng)發(fā)布
},
methods: {
handlePay() {
const { fee, paymentArgs, currencyType, version } = this.data
wx.requestPluginPayment({
fee,
paymentArgs,
currencyType,
version,
success(r) {
console.log(r)
},
fail(e) {
console.error(e)
}
})
}
}
})
# functionl-page-navigator 方式(將廢棄)
該方式將會(huì)被廢棄,僅供參考
<!-- plugin/components/pay.wxml -->
<!-- 上線時(shí),version 應(yīng)改為 "release",并確保插件所有者小程序已經(jīng)發(fā)布 -->
<!-- name 參數(shù)固定為 "requestPayment" -->
<functional-page-navigator
version="develop"
name="requestPayment"
args="{{ args }}"
bind:success="paymentSuccess"
bind:fail="paymentFailed"
>
<button class="payment-button">支付 0.01 元</button>
</functional-page-navigator>
// plugin/components/pay.js
Component({
data: {
args: {
fee: 1, // 支付金額,單位為分
paymentArgs: 'A', // 將傳遞到功能頁函數(shù)的自定義參數(shù)
currencyType: 'USD' // 貨幣符號,頁面顯示貨幣簡寫 US$
}
},
methods: {
// 支付成功的回調(diào)接口
paymentSuccess: function (e) {
console.log(e);
e.detail.extraData.timeStamp // 用 extraData 傳遞數(shù)據(jù),詳見下面功能頁函數(shù)代碼
},
// 支付失敗的回調(diào)接口
paymentFailed: function (e) {
console.log(e);
}
}
})
用戶調(diào)用 wx.requestPluginPayment 或點(diǎn)擊 navigator 后,將會(huì)進(jìn)行權(quán)限判斷,然后直接拉起支付收銀臺(tái)或跳轉(zhuǎn)到如下的支付功能頁:

# 配置功能頁函數(shù)
支付功能頁需要插件開發(fā)者在插件所有者小程序中提供一個(gè)函數(shù)來響應(yīng)插件中的支付調(diào)用。即,在插件中跳轉(zhuǎn)到支付功能頁或調(diào)用 wx.requestPluginPayment 時(shí),這個(gè)函數(shù)就會(huì)在合適的時(shí)機(jī)被調(diào)用,來幫助完成支付。如果不提供功能頁函數(shù),功能頁調(diào)用將通過 fail 事件返回失敗。
支付功能頁函數(shù)應(yīng)以導(dǎo)出函數(shù)的形式提供在插件所有者小程序的根目錄下的 functional-pages/request-payment.js 文件中,名為 beforeRequestPayment。該函數(shù)應(yīng)接收兩個(gè)參數(shù):
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
| paymentArgs | Object | 即通過 functional-page-navigator 的 arg 參數(shù)中的 paymentArgs 字段傳遞到功能頁的自定義數(shù)據(jù) |
| callback | Function | 回調(diào)函數(shù),調(diào)用該函數(shù)后,小程序?qū)l(fā)起支付(類似于 wx.requestPayment) |
callback 函數(shù)的參數(shù):
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
| error | Object | 失敗信息,若無失敗,應(yīng)返回 null |
| requestPaymentArgs | Object | 支付參數(shù),用于調(diào)用 wx.requestPayment,參數(shù)如下 |
requestPaymentArgs 的參數(shù):
用于發(fā)起支付,和 wx.requestPayment 的參數(shù)相同,但沒有回調(diào)函數(shù)(success, fail, complete):
| 參數(shù) | 類型 | 必填 | 說明 |
|---|---|---|---|
| timeStamp | String | 是 | 時(shí)間戳從 1970 年 1 月 1 日 00:00:00 至今的秒數(shù),即當(dāng)前的時(shí)間 |
| nonceStr | String | 是 | 隨機(jī)字符串,長度為 32 個(gè)字符以下。 |
| package | String | 是 | 統(tǒng)一下單接口返回的 prepay_id 參數(shù)值,提交格式如:prepay_id=*** |
| signType | String | 是 | 簽名算法,暫支持 MD5 |
| paySign | String | 是 | 簽名,具體簽名方案參見 小程序支付接口文檔; |
| extraData | any | 否 | 由開發(fā)者決定的自定義數(shù)據(jù)段,該字段將被無修改地透傳到支付成功的回調(diào)參數(shù)中,具體見代碼示例中的使用方法?;A(chǔ)庫 2.9.1 開始支持 |
了解更多信息,請查看 微信支付接口文檔
功能頁函數(shù)代碼示例:
// functional-pages/request-payment.js
exports.beforeRequestPayment = function (paymentArgs, callback) {
// 注意:
// 功能頁函數(shù)(這個(gè)函數(shù))不應(yīng) require 其他非 functional-pages 目錄中的文件,
// 其他非 functional-pages 目錄中的文件也不應(yīng) require 這個(gè)目錄中的文件,
// 這樣的 require 調(diào)用在未來將不被支持。
//
// 同在 functional-pages 中的文件可以 require
var getOpenIdURL = require('./URL').getOpenIdURL;
var paymentURL = require('./URL').paymentURL;
// 自定義的參數(shù),此處應(yīng)為從插件傳遞過來的 'A'
var customArgument = paymentArgs.customArgument;
// 第一步:調(diào)用 wx.login 方法獲取 code,然后在服務(wù)端調(diào)用微信接口使用 code 換取下單用戶的 openId
// 具體文檔參考 http://m.ceconline.net/debug/wxadoc/dev/api/api-login.html?t=20161230#wxloginobject
wx.login({
success: function (data) {
wx.request({
url: getOpenIdURL,
data: { code: data.code },
success: function (res) {
// 拉取用戶 openid 成功
// 第二步:在服務(wù)端調(diào)用支付統(tǒng)一下單,返回支付參數(shù)。這里的開發(fā)和普通的 wx.requestPayment 相同
// 文檔可以參考 https://pay.weixin.qq.com/doc/v2/merchant/4011938514
wx.request({
url: paymentURL,
data: { openid: res.data.openid },
method: 'POST',
success: function (res) {
console.log('unified order success, response is:', res);
var payargs = res.data.payargs;
// 第三步:調(diào)用回調(diào)函數(shù) callback 進(jìn)行支付
// 在 callback 中需要返回兩個(gè)參數(shù): err 和 requestPaymentArgs:
// err 應(yīng)為 null (或者一些失敗信息);
// requestPaymentArgs 將被用于調(diào)用 wx.requestPayment,除了 success/fail/complete 不被支持外,
// 應(yīng)與 wx.requestPayment 參數(shù)相同。
var error = null;
var requestPaymentArgs = {
timeStamp: payargs.timeStamp,
nonceStr: payargs.nonceStr,
package: payargs.package,
signType: payargs.signType,
paySign: payargs.paySign,
extraData: { // 用 extraData 傳遞自定義數(shù)據(jù)
timeStamp: payargs.timeStamp
},
};
callback(error, requestPaymentArgs);
}
});
},
fail: function (res) {
console.log('拉取用戶 openid 失敗,將無法正常使用開放接口等服務(wù)', res);
// callback 第一個(gè)參數(shù)為錯(cuò)誤信息,返回錯(cuò)誤信息
callback(res);
}
});
},
fail: function (err) {
console.log('wx.login 接口調(diào)用失敗,將無法正常使用開放接口等服務(wù)', err)
// callback 第一個(gè)參數(shù)為錯(cuò)誤信息,返回錯(cuò)誤信息
callback(err);
}
});
}
注意:功能頁函數(shù)不應(yīng) require 其他非 functional-pages 目錄中的文件,其他非 functional-pages 目錄中的文件也不應(yīng) require 這個(gè)目錄中的文件。這樣的 require 調(diào)用在未來將不被支持。
這個(gè)目錄和文件應(yīng)當(dāng)被放置在插件所有者小程序代碼中(而非插件代碼中),它是插件所有者小程序的一部分(而非插件的一部分)。 如果需要新增或更改這段代碼,需要發(fā)布插件所有者小程序,才能在正式版中生效;需要重新預(yù)覽插件所有者小程序,才能在開發(fā)版中生效。