企业付款API接口说明文档_V2 (1)(1)
合集下载
相关主题
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
表 4.2：证书文件说明
内部文档，请勿外传
证书附件
描述
使用场景
备注
pkcs12 格式 (apiclient_cert.p12)
包含了私钥信息的 撤销、退款申请 windows 上可以直接双
证书文件，为
API 中调用
击导入系统，导入过程中
p12(pfx)格式，由
会提示输入证书密码，证
微信支付签发给您
第二步：拼接支付密钥：
stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A
内部文档，请勿外传
9CF3B7" 最终得到最终发送的数据： <xml> <appid>wxd930ea5d5a258f4f</appid> <mch_id>10000100</mch_id> <device_info>1000<device_info> <body>test</body> <nonce_str>ibuaiVcKdpRxkhJA</nonce_str> <sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign> <xml> 微信提供相关接口在线签名验证工具：链接地址。
中导出密钥部分的 件，而需要使用 openssl pkcs12
文件，为 pem 格式 pem，为了方便 -nocerts -in
您使用，已为您 apiclient_cert.p12
直接提供
-out
内部文档，请勿外传
apiclient_key.pem CA 证书（rootca.pem） 微信支付 api 服务 该文件为签署 部分工具已经内置了若
1.2 接口介绍
业务流程 付款
接口 企业付款
简介 用于企业向微信用户个人付款 目前支持向指定微信用户的 openid 或微信号付 款。（获取 openid 参见微信公众平台开发者文 档: 网页授权获取用户基本信息，微信号需用户 主动告知）
2 企业付款接口
2.1 企业付款
2.1.1 接口说明 用于企业向微信用户个人付款 目前支持向指定微信用户的 openid 付款。（获取 openid 参见微信公众平台开发者文
商户 appid
微信支付分配的商户号
微信支付分配的终端设备号，
内部文档，请勿外传
随机字符 nonce_str 是
String( 随机字符串，不长于 32 位
串
32)
签名
sign
是 C380BEC2BF String( 生成签名方式查看 2.1 节
D727A4B684 32)
5133519F3A
D6
内部文档，请勿外传 档: 网页授权获取用户基本信息，微信号需用户主动告知）
2.1.2 接口调用请求说明
请求 Url
是否需要证书
是
2.1.3 请求参数
字段名
字段
公众账号 appid 商户号
mch_appid mchid
子商户号 sub_mchid
设备号 device_info
随机字符 nonce_str 串
内部文档，请勿外传
用户微信 weinxin_id 可
号
选
校验用户 check_name 是
姓名选项
收款用户 re_user_na 可
姓名
me
选
金额
amount
是
企业付款 desc
是
描述信息
Ip 地址 spbill_creat 是
e_ip
weiweiVIP OPTION_CHE CK
马总
10099 理赔 192.168.0.1
书密码默认为您的商户
用来标识和界定您
ID（如：10010000）
的身份
证书 pem 格式
从
PHP 等不能直 您也可以使用 openssl
（apiclient_cert.pem） apiclient_cert.p12 接使用 p12 文 命令来自己导出：
中导出证书部分的 件，而需要使用 openssl pkcs12
参数名 ASCII 码从小到大排序（字典序）；
内部文档，请勿外传
如果参数的值为空不参与签名；
参数名区分大小写；
验证调用返回或微信主动通知签名时，传送的 sign 参数不参与签名，将生成 的签名与该 sign 值作校验。
第二步，在 stringA 最后拼接上 key=商户支付密钥得到 stringSignTemp 字符串，并
3.2.2 生成随机数算法 微信支付 API 接口协议中包含固定 nonce_str，主要保证签名不可预测。我们推荐生成 随机数算法如下：调用随机数生成函数，将得到的值转换为字符串。
3.2.3 商户证书 1) 获取商户证书
微信支付接口中，涉及资金回滚的接口会使用到商户证书，包括退款、撤销接口。商家 在申请微信支付成功后，收到的相应邮件通知中，附件会包含接口需要用到的证书文件，有 四个证书文件，分别说明如下。
内部文档，请勿外传
企业付款API文档
(公司内部文档，请勿外传)
修订
时间
版本号
维护人
维护内容
内部文档，请勿外传
1 前言
1.1 业务介绍
企业付款业务是基于微信支付商户平台的资金管理能力，为了协助商户方便地实现企业 向个人付款，针对部分有开发能力的商户，提供通过 API 完成企业付款的功能。
比如目前的保险行业向客户退保、给付、理赔。
内部文档，请勿外传
器上也部署了证明 微信支付证书 干权威机构的根证书，无 微信支付身份的服 的权威机构的 需引用该证书也可以正 务器证书，您在使 根证书，可以用 常进行验证，这里提供给 用 api 进行调用时 来验证微信支 您在未内置所必须根证 也需要验证所调用 付服务器证书 书的环境中载入使用 服务器及域名的真 的真实性 实性 2) 使用商户证书 apiclient_cert.p12 是商户证书文件，除 PHP 外的开发均使用此证书文件。 商户如果使用.NET 环境开发，请确认 Framework 版本大于 2.0，必须在操作系统 上双击安装证书 apiclient_cert.p12 后才能被正常调用。 商户证书调用或安装都需要使用到密码，该密码的值为微信商户号（mchid） PHP 开发环境请使用商户证书文件 apiclient_cert.pem 和 apiclient_key.pem ， rootca.pem 是 CA 证书。 3) 商户证书安全 证书文件放在非 web 服务器虚拟目录的文件夹下，防止被他人下载。商户服务器要做 好病毒和木马防护工作，不被非法侵入者窃取证书文件。
对 stringSignTemp 进行 MD5 运算，再将得到的字符串所有字符转换为大写，得到 sign
值 signValue。
举例：
假设传送的参数如下：
appid： wxd930ea5d5a258f4f
mch_id：
1ቤተ መጻሕፍቲ ባይዱ000100
device_info： 1000
Body： test
nonce_str： ibuaiVcKdpRxkhJA
3.2 安全规范
3.2.1 签名算法 签名生成的通用步骤如下： 第一步，设所有发送或者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照 参 数 名 ASCII 码 从 小 到 大 排 序 （ 字 典 序 ）， 使 用 URL 键 值 对 的 格 式 （ 即 key1=value1&key2=value2…）拼接成字符串 stringA。 特别注意以下重要规则：
签名
sign
商户订单 partner_tra
号
de_no
用户账户 类型 用户 openid
user_type openid
必
示例值
类型
填
是 wx888888888 String
8888888
是 1900000109 String(
32)
否 1900000109 String(
32)
否 01346700704 String(
企业付款操作说明信息。必填。
调用接口的机器 Ip 地址
数据示例： Xml 待补充
2.1.4 返回参数
字段名 变量名
必 示例值
填
返回状态 return_code 是 SUCCESS
码
类型
String( 16)
返回信息 return_msg 否 签名失败
String( 128)
以下字段在 return_code 为 SUCCESS 的时候有返回
文件，为 pem 格 pem，为了方便 -clcerts -nokeys -in
式，请妥善保管不 您使用，已为您 apiclient_cert.p12
要泄漏和被他人复 直接提供
-out
制
apiclient_cert.pem
证书密钥 pem 格式
从
PHP 等不能直 您也可以使用 openssl
（apiclient_key.pem） apiclient_cert.p12 接使用 p12 文 命令来自己导出：
5764
32)
是 5K8264ILTKC String(
H16CQ2502SI 32)
8ZNMTM67V
S
是 C380BEC2BF String(
D727A4B684 32)
5133519F3A
D6
是 10000098201 String
41111123456
7890
是 OPEN_ID
String
可 oxTWIuGaIt6 选 gTKsQRLau2
String
String
Uint64 _t String String( 32)
如果 user_type 为 WEIXIN_ID，必填
NO_CHECK：不校验真实姓名 FORCE_CHECK：强校验真实姓名（未绑卡 用户会校验失败，无法转账） OPTION_CHECK：针对已绑卡的用户校验 真实姓名（未绑卡用户不校验） 收款用户真实姓名。 如果 check_name 设置为 FORCE_CHECK 或 OPTION_CHECK，则必填用户真实姓名 企业付款金额，单位为分
商 户 订 partner_tr 是
String 商户订单号，需保持唯一性
单号
ade_no
(32)
微 信 订 payment_ 是
String 企业付款成功，返回的微信订单号
单号
no
payment_ti 是
微信成
me 功时间
String
企业付款成功时间
示例： Xml 待补充
2.1.5 错误码
错误代码 描述
业务结果 result_code 是
String( SUCCESS/FAIL
16)
错误代码 err_code
否
String( 错误码信息
32)
错误代码 err_code_de 否
String( 结果信息描述
描述
s
128)
以下字段在 return_code 和 result_code 都为 SUCCESS 的时候有返回
第一步：对参数按照 key=value 的格式，并按照参数名 ASCII 字典序排序如下：
stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_i
d=10000100&nonce_str=ibuaiVcKdpRxkhJA";
M0yL16E
String
说明 商户 appid 微信支付分配的商户号 微信支付分配的子商户号，受理模式下必填 微信支付分配的终端设备号 随机字符串，不长于 32 位
生成签名方式查看 2.1 节
商户订单号，需保持唯一性
OPEN_ID：用户 openid WEIXIN_ID：用户微信号 商户 appid 下，某用户的 openid 如果 user_type 为 OPEN_ID，必填
原因
解决方案
内部文档，请勿外传
3 接口规则
与微信支付 API 文档保持一致。以下内容来自微信支付 API 文档。
3.1 协议规则
传输方式 为保证交易安全性，采用 HTTPS 传输 提交方式 采用 POST 方法提交 数据格式 提交和返回数据都为 XML 格式，根节点名为 xml 字符编码 统一采用 UTF-8 字符编码 签名算法 MD5 签名要求 请求和接收数据均需要校验签名，签名的详细方法请参考下文 证书要求 调用申请退款、撤销订单接口需要商户证书 判断逻辑 先判断协议字段返回，再判断业务返回，最后判断交易状态
商 户 mch_appid 是
String
appid
商户号 mchid
是
String(
32)
设备号 device_info 否
String(
32)
说明
SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否 成功需要查看 result_code 来判断 返回信息，如非空，为错误原因 签名失败 参数格式校验错误
内部文档，请勿外传
证书附件
描述
使用场景
备注
pkcs12 格式 (apiclient_cert.p12)
包含了私钥信息的 撤销、退款申请 windows 上可以直接双
证书文件，为
API 中调用
击导入系统，导入过程中
p12(pfx)格式，由
会提示输入证书密码，证
微信支付签发给您
第二步：拼接支付密钥：
stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A
内部文档，请勿外传
9CF3B7" 最终得到最终发送的数据： <xml> <appid>wxd930ea5d5a258f4f</appid> <mch_id>10000100</mch_id> <device_info>1000<device_info> <body>test</body> <nonce_str>ibuaiVcKdpRxkhJA</nonce_str> <sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign> <xml> 微信提供相关接口在线签名验证工具：链接地址。
中导出密钥部分的 件，而需要使用 openssl pkcs12
文件，为 pem 格式 pem，为了方便 -nocerts -in
您使用，已为您 apiclient_cert.p12
直接提供
-out
内部文档，请勿外传
apiclient_key.pem CA 证书（rootca.pem） 微信支付 api 服务 该文件为签署 部分工具已经内置了若
1.2 接口介绍
业务流程 付款
接口 企业付款
简介 用于企业向微信用户个人付款 目前支持向指定微信用户的 openid 或微信号付 款。（获取 openid 参见微信公众平台开发者文 档: 网页授权获取用户基本信息，微信号需用户 主动告知）
2 企业付款接口
2.1 企业付款
2.1.1 接口说明 用于企业向微信用户个人付款 目前支持向指定微信用户的 openid 付款。（获取 openid 参见微信公众平台开发者文
商户 appid
微信支付分配的商户号
微信支付分配的终端设备号，
内部文档，请勿外传
随机字符 nonce_str 是
String( 随机字符串，不长于 32 位
串
32)
签名
sign
是 C380BEC2BF String( 生成签名方式查看 2.1 节
D727A4B684 32)
5133519F3A
D6
内部文档，请勿外传 档: 网页授权获取用户基本信息，微信号需用户主动告知）
2.1.2 接口调用请求说明
请求 Url
是否需要证书
是
2.1.3 请求参数
字段名
字段
公众账号 appid 商户号
mch_appid mchid
子商户号 sub_mchid
设备号 device_info
随机字符 nonce_str 串
内部文档，请勿外传
用户微信 weinxin_id 可
号
选
校验用户 check_name 是
姓名选项
收款用户 re_user_na 可
姓名
me
选
金额
amount
是
企业付款 desc
是
描述信息
Ip 地址 spbill_creat 是
e_ip
weiweiVIP OPTION_CHE CK
马总
10099 理赔 192.168.0.1
书密码默认为您的商户
用来标识和界定您
ID（如：10010000）
的身份
证书 pem 格式
从
PHP 等不能直 您也可以使用 openssl
（apiclient_cert.pem） apiclient_cert.p12 接使用 p12 文 命令来自己导出：
中导出证书部分的 件，而需要使用 openssl pkcs12
参数名 ASCII 码从小到大排序（字典序）；
内部文档，请勿外传
如果参数的值为空不参与签名；
参数名区分大小写；
验证调用返回或微信主动通知签名时，传送的 sign 参数不参与签名，将生成 的签名与该 sign 值作校验。
第二步，在 stringA 最后拼接上 key=商户支付密钥得到 stringSignTemp 字符串，并
3.2.2 生成随机数算法 微信支付 API 接口协议中包含固定 nonce_str，主要保证签名不可预测。我们推荐生成 随机数算法如下：调用随机数生成函数，将得到的值转换为字符串。
3.2.3 商户证书 1) 获取商户证书
微信支付接口中，涉及资金回滚的接口会使用到商户证书，包括退款、撤销接口。商家 在申请微信支付成功后，收到的相应邮件通知中，附件会包含接口需要用到的证书文件，有 四个证书文件，分别说明如下。
内部文档，请勿外传
企业付款API文档
(公司内部文档，请勿外传)
修订
时间
版本号
维护人
维护内容
内部文档，请勿外传
1 前言
1.1 业务介绍
企业付款业务是基于微信支付商户平台的资金管理能力，为了协助商户方便地实现企业 向个人付款，针对部分有开发能力的商户，提供通过 API 完成企业付款的功能。
比如目前的保险行业向客户退保、给付、理赔。
内部文档，请勿外传
器上也部署了证明 微信支付证书 干权威机构的根证书，无 微信支付身份的服 的权威机构的 需引用该证书也可以正 务器证书，您在使 根证书，可以用 常进行验证，这里提供给 用 api 进行调用时 来验证微信支 您在未内置所必须根证 也需要验证所调用 付服务器证书 书的环境中载入使用 服务器及域名的真 的真实性 实性 2) 使用商户证书 apiclient_cert.p12 是商户证书文件，除 PHP 外的开发均使用此证书文件。 商户如果使用.NET 环境开发，请确认 Framework 版本大于 2.0，必须在操作系统 上双击安装证书 apiclient_cert.p12 后才能被正常调用。 商户证书调用或安装都需要使用到密码，该密码的值为微信商户号（mchid） PHP 开发环境请使用商户证书文件 apiclient_cert.pem 和 apiclient_key.pem ， rootca.pem 是 CA 证书。 3) 商户证书安全 证书文件放在非 web 服务器虚拟目录的文件夹下，防止被他人下载。商户服务器要做 好病毒和木马防护工作，不被非法侵入者窃取证书文件。
对 stringSignTemp 进行 MD5 运算，再将得到的字符串所有字符转换为大写，得到 sign
值 signValue。
举例：
假设传送的参数如下：
appid： wxd930ea5d5a258f4f
mch_id：
1ቤተ መጻሕፍቲ ባይዱ000100
device_info： 1000
Body： test
nonce_str： ibuaiVcKdpRxkhJA
3.2 安全规范
3.2.1 签名算法 签名生成的通用步骤如下： 第一步，设所有发送或者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照 参 数 名 ASCII 码 从 小 到 大 排 序 （ 字 典 序 ）， 使 用 URL 键 值 对 的 格 式 （ 即 key1=value1&key2=value2…）拼接成字符串 stringA。 特别注意以下重要规则：
签名
sign
商户订单 partner_tra
号
de_no
用户账户 类型 用户 openid
user_type openid
必
示例值
类型
填
是 wx888888888 String
8888888
是 1900000109 String(
32)
否 1900000109 String(
32)
否 01346700704 String(
企业付款操作说明信息。必填。
调用接口的机器 Ip 地址
数据示例： Xml 待补充
2.1.4 返回参数
字段名 变量名
必 示例值
填
返回状态 return_code 是 SUCCESS
码
类型
String( 16)
返回信息 return_msg 否 签名失败
String( 128)
以下字段在 return_code 为 SUCCESS 的时候有返回
文件，为 pem 格 pem，为了方便 -clcerts -nokeys -in
式，请妥善保管不 您使用，已为您 apiclient_cert.p12
要泄漏和被他人复 直接提供
-out
制
apiclient_cert.pem
证书密钥 pem 格式
从
PHP 等不能直 您也可以使用 openssl
（apiclient_key.pem） apiclient_cert.p12 接使用 p12 文 命令来自己导出：
5764
32)
是 5K8264ILTKC String(
H16CQ2502SI 32)
8ZNMTM67V
S
是 C380BEC2BF String(
D727A4B684 32)
5133519F3A
D6
是 10000098201 String
41111123456
7890
是 OPEN_ID
String
可 oxTWIuGaIt6 选 gTKsQRLau2
String
String
Uint64 _t String String( 32)
如果 user_type 为 WEIXIN_ID，必填
NO_CHECK：不校验真实姓名 FORCE_CHECK：强校验真实姓名（未绑卡 用户会校验失败，无法转账） OPTION_CHECK：针对已绑卡的用户校验 真实姓名（未绑卡用户不校验） 收款用户真实姓名。 如果 check_name 设置为 FORCE_CHECK 或 OPTION_CHECK，则必填用户真实姓名 企业付款金额，单位为分
商 户 订 partner_tr 是
String 商户订单号，需保持唯一性
单号
ade_no
(32)
微 信 订 payment_ 是
String 企业付款成功，返回的微信订单号
单号
no
payment_ti 是
微信成
me 功时间
String
企业付款成功时间
示例： Xml 待补充
2.1.5 错误码
错误代码 描述
业务结果 result_code 是
String( SUCCESS/FAIL
16)
错误代码 err_code
否
String( 错误码信息
32)
错误代码 err_code_de 否
String( 结果信息描述
描述
s
128)
以下字段在 return_code 和 result_code 都为 SUCCESS 的时候有返回
第一步：对参数按照 key=value 的格式，并按照参数名 ASCII 字典序排序如下：
stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_i
d=10000100&nonce_str=ibuaiVcKdpRxkhJA";
M0yL16E
String
说明 商户 appid 微信支付分配的商户号 微信支付分配的子商户号，受理模式下必填 微信支付分配的终端设备号 随机字符串，不长于 32 位
生成签名方式查看 2.1 节
商户订单号，需保持唯一性
OPEN_ID：用户 openid WEIXIN_ID：用户微信号 商户 appid 下，某用户的 openid 如果 user_type 为 OPEN_ID，必填
原因
解决方案
内部文档，请勿外传
3 接口规则
与微信支付 API 文档保持一致。以下内容来自微信支付 API 文档。
3.1 协议规则
传输方式 为保证交易安全性，采用 HTTPS 传输 提交方式 采用 POST 方法提交 数据格式 提交和返回数据都为 XML 格式，根节点名为 xml 字符编码 统一采用 UTF-8 字符编码 签名算法 MD5 签名要求 请求和接收数据均需要校验签名，签名的详细方法请参考下文 证书要求 调用申请退款、撤销订单接口需要商户证书 判断逻辑 先判断协议字段返回，再判断业务返回，最后判断交易状态
商 户 mch_appid 是
String
appid
商户号 mchid
是
String(
32)
设备号 device_info 否
String(
32)
说明
SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否 成功需要查看 result_code 来判断 返回信息，如非空，为错误原因 签名失败 参数格式校验错误