个人收款-结算请求用户确认收款

更新时间:2024.10.22

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

# 接口说明

支持商户:【平台商户】

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

接口名称: WeChatPayPlatSolutionEcommerce.requestPrepaySettleOrderConfirm

使用限制:

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

  2. 微信 OpenSDK 没有默认集成本接口,商户小程序需要额外安装 NPM 依赖(暂未发布,后续更新):

    1# 通过 NPM 安装: 微信支付(平台收付通-电商)小程序 SDK
    2npm install -S @tencent/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是否一致。

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

# 返回参数

# success 成功回调的参数
  • settleBatchNo 必填 string(64)
    【微信支付结算批次单号】 微信支付系统内部生成的结算批次单号,全局唯一对应一笔商户结算批次单号
  • outSettleBatchNo 必填 string(64)
    【商户结算批次单号】 商户在申请个人收款批量结算时传入的商户结算批次单号

成功回调的参数示例

# fail 失败回调的参数
  • code 必填 string(32)
    【错误码】 详见错误码部分
  • message 必填 string(1024)
    【失败原因】 不建议展示给用户,仅用于商户的开发人员定位失败原因

失败回调的参数示例

# 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\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

更多技术问题
技术咨询
反馈
咨询
目录