# 微信支付 - 统一下单
该接口方法需要安装 小程序微信支付能力,如未安装需要前往安装才可以使用
# 接口英文名
wxpay_order
注意:该接口仅支持在服务端调用
# 调用方式
# 1. 使用云函数调用云模板下单接口
模板已内置了云函数代码,可以直接在微信开发者工具中下载到本地修改后使用。 也可以手动创建云函数来完成,点击在线代码示例,可以查看云函数示例代码。
- 下载模板云函数代码到本地
打开微信开发者工具界面,在cloudfunctions
目录点击右键,选择同步云函数列表
,同步模板中的云函数wxpayFunctions
到本地;然后在云函数wxpayFunctions
目录右键,选择下载
,即可下载模板内置的云函数代码到本地。如下图所示:
- 编辑下单云函数
修改云函数wxpayFunctions
下的wxpay_order/index.js
代码,参数更新为业务实际参数。云函数编辑后,需要重新部署。
# 2. 小程序端获取预付单信息并完成支付
小程序端调用云函数时,需要先在小程序端初始化云能力。修改app.js
,在 App
的 onLaunch
生命周期方法中添加云能力初始化代码,参数传入用户的云开发环境ID。
App({
onLaunch: function () {
wx.cloud.init({
// env 参数决定接下来小程序发起的云开发调用(wx.cloud.xxx)会默认请求到哪个云环境的资源
env: '{%TCB_ENV_ID%}',
// 是否在将用户访问记录到用户管理中,在控制台中可见,默认为false
traceUser: false,
});
},
});
小程序中调用步骤 1 中的云函数,获取预付订单信息后,调用wx.requestPayment
唤起微信支付组件完成支付。
// 小程序代码
wx.cloud.callFunction({
// 云函数名称
name: 'wxpayFunctions',
data: {
// 调用云函数中的下单方法
type: 'wxpay_order',
// 业务其他参数...
},
success: (res) => {
console.log('下单结果: ', res);
const paymentData = res.result?.data;
// 唤起微信支付组件,完成支付
wx.requestPayment({
timeStamp: paymentData?.timeStamp,
nonceStr: paymentData?.nonceStr,
package: paymentData?.packageVal,
paySign: paymentData?.paySign,
signType: 'RSA', // 该参数为固定值
success(res) {
// 支付成功回调,实现自定义的业务逻辑
console.log('唤起支付组件成功:', res);
},
fail(err) {
// 支付失败回调
console.error('唤起支付组件失败:', err);
},
});
},
});
# 3. 接收并处理支付通知(可选)
如果插件配置中配置了接收支付通知的回调函数
,则可以在自定义的云函数中接收到支付通知,通知中包含了订单详细信息,商户可自行处理并存储。
# 支付通知
模板wxpay
可配置接收支付通知的回调函数
,目前支持配置商户当前云开发环境下的一个或多个(以英文逗号,
分隔)云函数,模板会将支付通知消息下发给商户配置的云函数,商户可以在云函数中对消息进行处理。
注意 商户接收并处理支付通知消息时,如果微信收到应答不是成功或超时,则认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但不保证通知最终能成功。
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。推荐的做法是,当商户系统收到通知进行处理时,先检查对应业务数据的状态,并判断该通知是否已经处理。如果未处理,则再进行处理;如果已处理,则直接返回结果成功。
- 如果在所有通知频率后没有收到微信侧回调。商户应调用查询订单接口确认订单状态。
通知规则 如果微信收到商户的应答不符合规范或超时,则认为通知失败,会通过一定的策略定期重新发起通知来尽可能提高通知的成功率,但不保证通知最终能成功(通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m)
商户通知应答
- 返回的包体包含字段
code
值为SUCCESS
,标识商户接收消息通知成功;- 除成功包体外的其他响应格式,视为商户接收消息失败;
- 如果商户配置了多个接收消息通知的云函数,则所有函数都返回成功包体,才视为接收消息成功;否则,微信重试时会重复通知到所有的云函数。
# 更多说明
错误码请参考微信小程序下单
# 入参:
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
description | string | 是 | 商品描述 |
out_trade_no | string | 是 | 商户订单号 |
amount | object | 是 | |
amount.total | number | 否 | 总金额 |
amount.currency | string | 否 | 货币类型。CNY:人民币,境内商户号仅支持人民币。 |
payer | object | 否 | 支付者信息 |
payer.openid | string | 否 | 用户在普通商户AppID下的唯一标识。 |
time_expire | string | 否 | 订单失效时间 |
attach | string | 否 | 附加数据,在查询API和支付通知中原样返回,可作为自定义参数使用,实际情况下只有支付完成状态才会返回该字段。 |
goods_tag | string | 否 | 订单优惠标记 |
support_fapiao | boolean | 否 | 电子发票入口开放标识 |
detail | object | 否 | 优惠功能 |
detail.cost_price | number | 否 | 订单原价 |
detail.invoice_id | string | 否 | 商品小票ID |
detail.goods_detail | array of object | 否 | |
detail.goods_detail[].goods_name | string | 否 | 商品名称 |
detail.goods_detail[].wechatpay_goods_id | string | 否 | 微信支付商品编码 |
detail.goods_detail[].quantity | number | 否 | 商品数量 |
detail.goods_detail[].merchant_goods_id | string | 否 | 商户侧商品编码 |
detail.goods_detail[].unit_price | number | 否 | 商品单价 |
scene_info | object | 否 | 支付场景描述 |
scene_info.device_id | string | 否 | 商户端设备号 |
scene_info.payer_client_ip | string | 否 | 用户终端IP |
scene_info.store_info | object | 否 | |
scene_info.store_info.id | string | 否 | 门店编号 |
scene_info.store_info.name | string | 否 | 门店名称 |
scene_info.store_info.address | string | 否 | 详细地址 |
scene_info.store_info.area_code | string | 否 | 地区编码 |
settle_info | object | 否 | 结算信息 |
settle_info.profit_sharing | boolean | 否 | 是否指定分账 |
# 出参:
参数 | 类型 | 描述 |
---|---|---|
requestID | string | 当前请求唯一ID |
result | object | |
result.code | number | 响应码 |
result.data | object | |
result.data.appId | string | 小程序appId |
result.data.nonceStr | string | 随机字符串 |
result.data.packageVal | string | 统一下单接口返回的 prepay_id 参数值 |
result.data.paySign | string | 签名 |
result.data.signType | string | 签名算法 |
result.data.timeStamp | string | 时间戳,从 1970 年 1 月 1 日 00:00:00 至今的秒数 |