结算请求用户确认收款

更新时间:2024.11.26

商户在 申请个人收款批量结算 后,可通过商户的小程序调用微信支付 SDK,请求用户确认收款。

接口说明

支持商户:【平台商户】

支持的调用端:【小程序】

接口名称:WeChatPayPlatSolutionEcommerce.requestPrepaySettleOrderConfirm

使用限制:

  1. 仅限已开通该接口权限的小程序调用,且调用方小程序的 AppID 必须与申请个人收款批量结算时提供的 AppID 一致。

  2. 微信 OpenSDK 没有默认集成本接口,商户小程序需要额外安装 NPM 依赖

    1# 通过 NPM 安装: 微信支付(平台收付通-电商)小程序 SDK
    2npm install -S @tenpay/wechatpay-miniprogram-platsolution-ecommerce
  3. iOS 及 Android 微信客户端版本 8.0.51 开始支持。如客户端不支持,微信会向用户展示提示页面,并触发商户小程序失败回调。

提示

回调成功不代表结算收款成功,具体状态应以服务端收到回调或主动查单的详情为准。

字段说明

请求参数

mchid 必填 string(32)

【商户号】平台商户号


appid 必填 string(32)

【小程序 AppID】调用方小程序的 AppID,必须与申请个人收款批量结算时提供的 AppID 一致


package 必填 string(256)

【结算详情扩展字符串】需拼接申请个人收款批量结算接口返回的 settle_batch_no,参数格式:settle_batch_no=***


timeStamp 必填 string(32)

【签名时间戳】签名时的系统时间戳,自格林威治时间 1970-01-01 00:00:00(北京时间 1970-01-01 08:00:00)至现在的总秒数。

注意:部分系统取到的值为毫秒级,需要转换成秒(10位数字)。


nonceStr 必填 string(32)

【签名随机串】签名使用的随机字符串,不超过 32 字节


signType 必填 string(32)

【签名类型】默认为 RSA,仅支持 RSA


certSerialNo 必填 string(64)

【证书序列号】签名使用的商户 API 证书序列号


signature 必填 string(512)

【签名值】使用字段 appid timeStamp nonceStr package 计算得出的签名值,具体算法见下文签名步骤。

签名所使用的 appid 为申请个人收款批量结算时传入的 appid,微信支付会校验当前小程序与申请的 AppID 是否一致。

小程序调起确认收款页示例

1import WeChatPayPlatSolutionEcommerce from '@tenpay/wechatpay-miniprogram-platsolution-ecommerce';
2
3WeChatPayPlatSolutionEcommerce.requestPrepaySettleOrderConfirm({
4  mchid: '1900000000',
5  appid: 'wx8888888888888888',
6  package: 'settle_batch_no=1236698745558870',
7  timeStamp: '1414561699',
8  nonceStr: '5K8264ILTKCH16CQ2502SI8ZNMTM67VS',
9  signType: 'RSA',
10  certSerialNo: 'ABCDEFG0123456789',
11  signature: 'oR9d8PuhnIc+YZ8cBHFCwfgp...',
12  success: function (res) {
13    // 已确认收款, 结算结果以服务端回调为准
14  },
15  fail: function (err) {
16    // 确认收款失败, 详见: `err.code` `err.message`
17  },
18  complete: function () {
19    // 无论成功/失败均会回调
20  },
21});

 

返回参数

success 成功回调的参数

settleBatchNo 必填 string(64)

【微信支付结算批次单号】微信支付系统内部生成的结算批次单号,全局唯一对应一笔商户结算批次单号


outSettleBatchNo 必填 string(64)

【商户结算批次单号】商户在申请个人收款批量结算时传入的商户结算批次单号

成功回调的参数示例

1{
2  settleBatchNo: "1236698745558870",
3  outSettleBatchNo: "AAA12345678",
4}
fail 失败回调的参数

code 必填 string(32)

【错误码】

详见错误码部分


message 必填 string(1024)

【失败原因】

不建议展示给用户,仅用于商户的开发人员定位失败原因

失败回调的参数示例

1{
2  code: "PARAM_ERROR",
3  message: "timeStamp 格式有误"
4}
complete 完成回调的参数

没有参数。

无论成功、失败都会触发 complete 回调。

错误码

错误码

描述

解决方案

PARAM_ERROR

参数错误

请检查传入参数是否符合格式要求

INVALID_REQUEST

请求失败

参数格式正确,但不符合业务规则,请查看失败原因

SIGN_ERROR

签名验证不通过

请参阅 签名常见问题

NO_AUTH

无接口权限

没有调用此接口的权限,请查看失败原因

注意:拉起确认收款的小程序 AppID 应与申请批量结算时填写的 AppID 一致

RATELIMIT_EXCEEDED

频率超限

请降低请求接口频率

USER_ERROR

用户原因失败

客户端不受支持、用户主动取消、网络异常等用户原因失败,通常无需处理

注意:网络异常时,可能用户已发出确认请求,最终收款状态请以服务端回调或主动查单为准

ALREADY_EXISTS

资源已经存在

请求创建的资源重复,或者请求执行的操作已经完成,请检查资源状态

例如:存在已受理过的结算单,不可重复发起结算

SYSTEM_ERROR

系统异常,请稍后再试

请稍后再试

签名步骤

构造待签名串

待签名串共有四行,每行为一个参数值,并以 \n(换行符,ASCII 编码值为 0x0A)结尾,最后一行也需要以 \n 结尾。

如果参数值以 \n 结束,也需要额外附加一个 \n

待签名串的结构:

1小程序AppID\n
2签名时间戳\n
3随机字符串\n
4结算详情扩展字符串\n

待签名串的内容示例:

1wx8888888888888888\n
21414561699\n
35K8264ILTKCH16CQ2502SI8ZNMTM67VS\n
4settle_batch_no=1236698745558870\n

计算签名值

使用商户私钥对 待签名串 进行 SHA256 with RSA 签名,并对签名结果进行 Base64 编码,得到签名值 signature

以命令行为例:

1echo -n -e \
2"wx8888888888888888\n1414561699\n5K8264ILTKCH16CQ2502SI8ZNMTM67VS\nsettle_batch_no=1236698745558870\n" \
3  | openssl dgst -sha256 -sign apiclient_key.pem \
4  | openssl base64 -A

输出结果示例:

1uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r5wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI1XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8alLDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/4nLBiCwIUFluw==

在以上计算签名值的过程中,没有使用到 signType 参数,但调用接口时仍需要传递默认值 RSA

 

 

反馈
咨询
目录
置顶