小程序金额控件开发指引

更新时间：2024.12.30

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

# 使用限制

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

# 使用自定义的金额控件

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

# 方案一

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

代码示例:

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

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

# 方案二

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

代码示例:

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)

# 示例程序

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

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

# 进一步阅读

小程序金额控件介绍

文档是否有帮助

商户文档

商户文档中心

更多支持

开发者社区微信开放平台微信公众平台腾讯客服