个人收款-结算请求用户确认收款
更新时间:2024.10.22商户在 申请个人收款批量结算 后,可通过商户的小程序调用微信支付 SDK,请求用户确认收款。
# 接口说明
支持商户:【平台商户】
支持的调用端:【小程序】
接口名称: WeChatPayPlatSolutionEcommerce.requestPrepaySettleOrderConfirm
使用限制:
仅限已开通该接口权限的小程序调用,且调用方小程序的 AppID 必须与申请个人收款批量结算时提供的 AppID 一致。
微信 OpenSDK 没有默认集成本接口,商户小程序需要额外安装 NPM 依赖(暂未发布,后续更新):
1# 通过 NPM 安装: 微信支付(平台收付通-电商)小程序 SDK2npm install -S @tencent/wechatpay-miniprogram-platsolution-ecommerceiOS 及 Android 微信客户端版本 8.0.51 开始支持。如客户端不支持,微信会向用户展示提示页面,并触发商户小程序失败回调。
提示
回调成功不代表结算收款成功,具体状态应以服务端收到回调或主动查单的详情为准。
# 字段说明
# 请求参数
- mchid 必填【商户号】 平台商户号
- appid 必填【小程序 AppID】 调用方小程序的 AppID,必须与申请个人收款批量结算时提供的 AppID 一致
- package 必填【结算详情扩展字符串】 需拼接申请个人收款批量结算接口返回的
settle_batch_no
,参数格式:settle_batch_no=***
- timeStamp 必填【签名时间戳】 签名时的系统时间戳,自格林威治时间 1970-01-01 00:00:00(北京时间 1970-01-01 08:00:00)至现在的总秒数。
注意:部分系统取到的值为毫秒级,需要转换成秒(10位数字)。 - nonceStr 必填【签名随机串】 签名使用的随机字符串,不超过 32 字节。
- signType 必填【签名类型】 默认为RSA,仅支持RSA
- certSerialNo 必填【证书序列号】 签名使用的商户 API 证书序列号
- signature 必填【签名值】 使用字段
appid
timeStamp
nonceStr
package
计算得出的签名值,具体算法见下文签名步骤。
签名所使用的appid
为申请个人收款批量结算时传入的appid
,微信支付会校验当前小程序与申请的AppID是否一致。
小程序调起确认收款页示例
# 返回参数
# success 成功回调的参数
- settleBatchNo 必填【微信支付结算批次单号】 微信支付系统内部生成的结算批次单号,全局唯一对应一笔商户结算批次单号
- outSettleBatchNo 必填【商户结算批次单号】 商户在申请个人收款批量结算时传入的商户结算批次单号
成功回调的参数示例
# fail 失败回调的参数
- code 必填【错误码】 详见错误码部分
- message 必填【失败原因】 不建议展示给用户,仅用于商户的开发人员定位失败原因
失败回调的参数示例
# complete 完成回调的参数
没有参数。
无论成功、失败都会触发complete
回调。
# 错误码
错误码 | 描述 | 解决方案 |
---|---|---|
PARAM_ERROR | 参数错误 | 请根据失败原因检查传入参数 |
INVALID_REQUEST | 请求失败 | 因业务原因失败,请查看失败原因 |
SIGN_ERROR | 签名验证不通过 | 请参阅 签名常见问题 (opens new window) |
NO_AUTH | 无接口权限 | 请商户申请此接口的权限 注意:拉起确认收款的小程序 AppID 应与申请权限的 AppID 一致 |
RATELIMIT_EXCEEDED | 频率超限 | 请降低请求接口频率 |
USER_ERROR | 用户原因失败 | 客户端不受支持、账号异常或用户主动取消,请服务端等待回调或主动查单确认详情 |
SYSTEM_ERROR | 系统异常,请稍后再试 | 请稍后再试 |
# 签名步骤
# 构造待签名串
待签名串共有四行,每行为一个参数值,并以 \n
(换行符,ASCII 编码值为0x0A
)结尾,最后一行也需要以\n
结尾。
如果参数值以 \n
结束,也需要额外附加一个 \n
。
待签名串的结构:
1小程序AppID\n2时间戳\n3随机字符串\n4结算详情扩展字符串\n
待签名串的内容示例:
1wx8888888888888888\n21414561699\n35K8264ILTKCH16CQ2502SI8ZNMTM67VS\n4settle_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
。
文档是否有帮助