结算请求用户确认收款
更新时间:2024.11.26商户在 申请个人收款批量结算 后,可通过商户的小程序调用微信支付 SDK,请求用户确认收款。
接口说明
支持商户:【平台商户】
支持的调用端:【小程序】
接口名称:WeChatPayPlatSolutionEcommerce.requestPrepaySettleOrderConfirm
使用限制:
仅限已开通该接口权限的小程序调用,且调用方小程序的 AppID 必须与申请个人收款批量结算时提供的 AppID 一致。
微信 OpenSDK 没有默认集成本接口,商户小程序需要额外安装 NPM 依赖:
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 是否一致。
小程序调起确认收款页示例
返回参数
success 成功回调的参数
settleBatchNo 必填 string(64)
【微信支付结算批次单号】微信支付系统内部生成的结算批次单号,全局唯一对应一笔商户结算批次单号
outSettleBatchNo 必填 string(64)
【商户结算批次单号】商户在申请个人收款批量结算时传入的商户结算批次单号
成功回调的参数示例
fail 失败回调的参数
code 必填 string(32)
【错误码】
详见错误码部分
message 必填 string(1024)
【失败原因】
不建议展示给用户,仅用于商户的开发人员定位失败原因
失败回调的参数示例
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
。
待签名串的结构:
待签名串的内容示例:
计算签名值
使用商户私钥对 待签名串 进行 SHA256 with RSA
签名,并对签名结果进行 Base64 编码,得到签名值 signature
。
以命令行为例:
输出结果示例:
在以上计算签名值的过程中,没有使用到 signType
参数,但调用接口时仍需要传递默认值 RSA
。