小程序金额控件开发指引

更新时间：2024.11.20

在付款页面展示微信支付金额控件，该控件由金额输入区和键盘组成，用户使用该控件输入金额并轻触付款后完成支付流程。

使用限制

微信客户端版本 8.0.40 开始支持，低版本需要使用自定义金额组件做兼容处理 - 使用自定义的金额控件。

开发指引

安装 NPM 包

请在本地开发环境使用NPM安装依赖包

1npm install -S @tenpay/wechatpay-miniprogram

组件初始化

在小程序page.json处引入组件完成初始化，，初始化后即可引用 WechatPayMiniProgram 类和使用扫码支付的wechatpay-payment金额控件。

1"usingComponents": {
2        "wechatpay-payment": "@tencent/wechatpay-miniprogram/WechatPayment"
3    }

判断是否支持金额控件

通过 WechatPayMiniProgram.isSupportScanPosPay 方法判断当前微信客户端是否支持金额控件。

1// 示例代码
2// 使用WechatPayMiniProgram前先导入
3import WechatPayMiniProgram from '@tenpay/wechatpay-miniprogram';
4
5// 判断当前微信客户端版本是否支持金额控件
6const supportScanPosPay = await WechatPayMiniProgram.isSupportScanPosPay();
7
8// supportScanPosPay为true表示当前微信客户端支持金额控件
9// supportScanPosPay为false表示当前微信客户端不支持金额控件

支持金额控件

使用 wechatpay-payment 标签展示金额控件

1<!-- 展示金额控件 -->
2<wechatpay-payment
3    class="payment-style"
4    bind:onPayTouch="onPayTouch"
5    bind:onPaySuccess="onPaySuccess"
6    bind:onPayFailed="onPayFailed"
7></wechatpay-payment>
8
9<style>
10/* 通过css样式控制金额输入框的位置，大小，边框等属性 */
11.payment-style {
12  display: block;
13  margin: 20px;
14  padding: 10px;
15  border-bottom: 0.5px solid;
16  border-color: rgba(0, 0, 0, 0.1);
17}
18</style>

不支持金额控件

请参考自定义的金额控件

使用默认金额控件

在付款页面中使用微信支付组件 wechatpay-payment 展示金额控件，商户需要实现onPayTouch、onPaySuccess和onPayFailed 三个事件的回调处理函数。

客户端支付状态	控件回调事件	行为描述	注意事项
展示金额输入控件	-	【商户前端】使用 `wechatpay-payment` 标签展示金额控件
用户修改支付金额	-	【金额控件】展示用户付款金额并记录 `amount` 金额参数
用户点击 `付款`	onPayTouch	【商户前端】根据事件回调的 `amount` 金额参数，调用【商户后端】完成下单。【商户前端】下单完成后，调用`orderCompleteCallback`函数传入订单信息调起【商业支付收银台】，继续支付流程。请参考orderCompleteCallback接口说明	如果在`onPayTouch`事件触发后30秒内未完成下单并调用`orderCompleteCallback`，流程自动走到支付失败逻辑，此时触发 `onPayFailed` 事件，回调事件中`retcode`返回`OrderTimeout`
用户等待支付	-	【金额控件】等待商户下单过程中屏幕将展示 `loading` 加载状态，此时用户无法进行其他操作。
展示收银台	-	【商业支付收银台】等待用户完成支付鉴权。
用户支付成功	onPaySuccess	【用户】在【商业支付收银台】支付成功后，【商户前端】收到支付成功回调事件。	请通过后台查单确定订单状态，如果商户查单接口明确返回支付成功，则给用户展示支付成功页。
用户支付失败取消支付	onPayFailed	【用户】主动取消支付后，【商户前端】收到支付失败事件，回调事件中`retcode`返回`Cancel`。
用户支付失败下单超时	onPayFailed	【用户】点击`付款`后，若30秒内【商户前端】未调用`orderCompleteCallback`函数，则触发下单超时，【商户前端】收到支付失败事件，回调事件中`retcode`返回`OrderTimeout`。
用户支付失败其他异常	onPayFailed	如果回调事件中`retcode`返回`PayFail`，则表示由于其他未知情况导致的支付失败。

控件代码示例

1// 点击付款时回调
2async onPayTouch(event: {detail: OnPayTouchEvent}) {
3  const detail = event.detail;
4  try {
5    // 从 detail.amount 中获取用户输入的金额，可以根据后端协议转换为相应的单位，转换时注意处理精度问题
6    const amount = Math.round(detail.amount * 100);
7    // 调用商户后台接口进行下单
8    const resp = await createOrder(amount);
9    if (resp.retcode === 0) {
10      // 下单成功后，调用orderCompleteCallback继续支付流程。orderInfo一般由商户后端生成，格式参考如下代码示例
11      const orderInfo = {
12          "appId":"wx2421b1c4370ec43b",
13          "timeStamp":"1395712654",
14          "nonceStr":"e61463f8efa94090b1f366cccfbbb444",
15          "package":"prepay_id=up_wx21201855730335ac86f8c43d1889123400",
16          "signType":"RSA",
17          "paySign":"oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbX++IOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg=="
18      }
19      await detail.orderCompleteCallback(true, orderInfo);
20    } else {
21      // 下单明确失败后，调用orderCompleteCallback取消支付流程
22      await detail.orderCompleteCallback(false, null);
23    }
24  } catch(error) {
25    // 其他异常情况，调用orderCompleteCallback取消支付流程
26    await detail.orderCompleteCallback(false, null);
27  }
28}
29// 支付成功时回调
30onPaySuccess(event: {detail: OnPaySuccessEvent}) {
31  // 请求商户后台查单确定订单状态、其他处理逻辑...
32}
33// 支付失败时回调
34onPayFailed(event: {detail: OnPayFailedEvent}) {
35  // 其他处理逻辑...
36},

使用自定义的金额控件

低版本客户端不支持金额控件，需要进行兼容处理，有两种兼容方案：

方案一

在NPM包example/compatible目录下提供了 payment-custom 组件，该组件封装了和 wechatpay-payment 相同的功能和参数，商户可以参考该组件示例实现兼容逻辑，如有需求可以修改 payment-custom 组件代码。

代码示例:

1// 示例代码
2// 使用WechatPayMiniProgram前先导入
3import WechatPayMiniProgram from '@tenpay/wechatpay-miniprogram';
4
5// 判断当前微信客户端版本是否支持金额控件
6const supportScanPosPay = await WechatPayMiniProgram.isSupportScanPosPay();
7
8// supportScanPosPay为true表示当前微信客户端支持金额控件
9// supportScanPosPay为false表示当前微信客户端不支持金额控件

1<!-- 示例代码 -->
2<!-- 不支持金额控件时使用自定义金额控件 -->
3<payment-custom 
4  class="payment-style"
5  bind:onPayTouch="onPayTouch"
6  bind:onPaySuccess="onPaySuccess"
7  bind:onPayFailed="onPayFailed"
8>
9</payment-custom>
10
11<style>
12/* 通过css样式控制金额输入框的位置，大小，边框等属性 */
13.payment-style {
14  display: block;
15  margin: 20px;
16  padding: 10px;
17  border-bottom: 0.5px solid;
18  border-color: rgba(0, 0, 0, 0.1);
19}
20</style>

方案二

商户在低版本微信客户端使用小程序支付实现兼容逻辑。参考小程序支付开发指引。

代码示例:

1wx.requestPayment
2(
3  {
4    "timeStamp": "1414561699",
5    "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
6    "package": "prepay_id=wx201410272009395522657a690389285100",
7    "signType": "RSA",
8    "paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbX++IOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg==",
9    "success":function(res){},
10    "fail":function(res){},
11    "complete":function(res){}
12  }
13)

示例程序

为了便于开发者快速接入小程序金额控件，降低接入门槛，我们开发了基于小程序的示例程序。

在 example/compatible/pages/index 可以看到完整的使用例子。

进一步阅读

小程序金额控件介绍

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服