接口说明

设置单个红包的金额,类型等,生成红包信息。预下单完成后,需要在72小时内调用jsapi完成抽红包的操作。(红包过期失效后,资金会退回到商户财付通账号。)

接口调用说明

服务器端调用
http请求方式: POST<a href="https://api.mch.weixin.qq.com/mmpaymkttransfers/hbpreorder" target="_blank">https://api.mch.weixin.qq.com/mmpaymkttransfers/hbpreorder</a>

POST数据格式:XML
需要商户证书

请求参数说明

参数 字段 是否必须 示例值 类型 说明
随机字符串 nonce_str 5K8264ILTKCH16CQ2502SI8Z NMTM67VS String(32) 随机字符串,不长于32位
签名 sign C380BEC2BFD727A4B68451335 19F3AD6 String(32) 生成签名方式查看签名算法
商户订单号 mch_billno 10000098201411111234567890 String(28) 商户订单号(每个订单号必须唯一)组成: mch_id+yyyymmdd+10位一天内不能重复的数字。接口根据商户订单号支持重入, 如出现超时可再调用。
商户号 mch_id 10000098 String(32) 红包提供者的商户号(微信支付分配的商户号)
公众账号appid wxappid wx8888888888888888 String(32) 红包提供者公众号的appid,对应头像展示在红包页面
商户名称 send_name 天虹百货 String(32) 红包提供者名称,展示在红包页面
红包类型 hb_type NORMAL String(16) NORMAL-普通红包;GROUP-裂变红包(可分享红包给好友,无关注公众号能力)。
总金额 total_amount 1000 int 总付款金额,单位分
红包发放总人数 total_num 1 int 红包发放总人数,即总共有多少人可以领到该组红包(包括分享者)。普通红包填1,裂变红包必须大于1。
红包金额设置方式 amt_type ALL_RAND String(32) 红包金额设置方式,只对裂变红包生效。ALL_RAND—全部随机
红包祝福语 wishing 感谢您参加猜灯谜活动,祝您元宵节快乐 String(16) 红包祝福语,展示在红包页面
活动名称 act_name 猜灯谜抢红包活动 String(32) 活动名称,在不支持原生红包的微信版本中展示在红包消息
备注 remark 猜越多得越多,快来抢! String(32) 备注信息,在不支持原生红包的微信版本中展示在红包消息
授权商户号 auth_mchid 1000052601 String(32) 用于发红包时微信支付识别摇周边红包,所有开发者统一填写摇周边平台的商户号:1000052601
授权商户APPID auth_appid wxbf42bd79c4391863 String(32) 用于发红包时微信支付识别摇周边红包,所有开发者统一填写摇周边平台的appid:wxbf42bd79c4391863
风控设置 risk_cntl NORMAL String(32) 用于管控接口风险。具体值如下:NORMAL—正常情况;IGN_FREQ_LMT—忽略防刷限制,强制发放;IGN_DAY_LMT—忽略单用户日限额限制,强制发放;IGN_FREQ_DAY_LMT—忽略防刷和单用户日限额限制,强制发放;如无特殊要求,请设为NORMAL。若忽略某项风险控制,可能造成资金损失,请谨慎使用。

请求示例

<xml>     
<sign><![CDATA[E1EE61A91C8E90F299DE6AE075D60A2D]]></sign>     
<mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno>     
<mch_id><![CDATA[10000097]]></mch_id>     
<wxappid><![CDATA[wxcbda96de0b165486]]></wxappid>     
<send_name><![CDATA[send_name]]></send_name>     
<hb_type><![CDATA[NORMAL]]></hb_type>     
<auth_mchid><![CDATA[10000098]]></auth_mchid>     
<auth_appid><![CDATA[wx7777777]]></auth_appid>     
<total_amount><![CDATA[200]]></total_amount>     
<amt_type><![CDATA[ALL_RAND]]></amt_type>     
<total_num><![CDATA[3]]></total_num>     
<wishing><![CDATA[恭喜发财 ]]></wishing>     
<act_name><![CDATA[ 新年红包 ]]></act_name>     
<remark><![CDATA[新年红包 ]]></remark>     
<risk_cntl><![CDATA[NORMAL]]></risk_cntl>     
<nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str>
</xml>

返回数据说明

返回格式为xml

参数 字段 是否必须 示例值 类型 说明
返回状态码 return_code SUCCESS String(16) SUCCESS/FAIL;此字段是通信标识,非交易标识,交易是否成功需要查看result_code来判断
返回信息 return_msg 签名失败 String(128) 返回信息,如非空,为错误原因 签名失败 参数格式校验错误

以下字段在return_code为SUCCESS的时候有返回

参数 字段 是否必须 示例值 类型 说明
签名 sign C380BEC2BFD727A4B6845133519F3AD6 String(32) 生成签名方式查看 签名算法
业务结果 result_code SUCCESS String(16) SUCCESS/FAIL
错误代码 err_code SUCCESS String(32) 错误码信息
错误代码描述 err_code_des 系统错误 String(128) 结果信息描述

以下字段在return_code 和result_code都为SUCCESS的时候有返回

参数 字段 是否必须 示例值 类型 说明
商户订单号 mch_billno 10000098201411111234567890 String(28) 商户订单号(每个订单号必须唯一)组成: mch_id+yyyymmdd+10位一天内不能重复的数字。
商户号 mch_id 10000098 String(32) 微信支付分配的商户号
公众账号appid wxappid wx8888888888888888 String(32) 商户appid
总金额 total_amount 1000 int 总付款金额,单位分
ticket sp_ticket 2J6MtR+SlbZ8Ga4EDi64X5 vC4Xv01ofX4uWOqqTc9kGJYhkq5 st5ucrXKxkjnC/UuvLeuhdIfiYg i4hJuJ95qjt9mwxqSBEmjGbZlL+ sqM9upoWsEjup28KPvaVrdao/Hg 6WqyqUL5E2zPHfM1sb1w== String sp_ticket,一个普通红包对应一个ticket
红包订单号 detail_id 0000000666201504290000042120 红包内部订单号
发送时间 20150429203444 红包发放时间

成功示例

<xml> 
<return_code><![CDATA[SUCCESS]]></return_code> 
<return_msg><![CDATA[发放成功.]]></return_msg> 
<result_code><![CDATA[SUCCESS]]></result_code> 
<err_code><![CDATA[0]]></err_code> 
<err_code_des><![CDATA[发放成功.]]></err_code_des> 
<mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno> 
<mch_id>10010404</mch_id> 
<wxappid><![CDATA[wx6fa7e3bab7e15415]]></wxappid> 
<sp_ticket><![CDATA[0cca98c8c8e814883]]></sp_ticket> 
<total_amount>3</total_amount> 
<detail_id><![CDATA[001001040420141117000004888]]></detail_id> 
<send_time><![CDATA[20150101080000]]></send_time> 
</xml>

失败示例

<xml>     
<return_code><![CDATA[FAIL]]></return_code> 
<return_msg><![CDATA[系统繁忙,请稍后再试.]]></return_msg> 
<result_code><![CDATA[FAIL]]></result_code> 
<err_code><![CDATA[268458547]]></err_code> 
<err_code_des><![CDATA[系统繁忙,请稍后再试.]]></err_code_des> 
<mch_billno><![CDATA[0010010404201411170000046542]]></mch_billno>        
<mch_id>10010404</mch_id> 
<wxappid><![CDATA[wx6fa7e3bab7e15415]]></wxappid> 
<total_amount>3</total_amount> 
</xml>

错误码

错误代码 描述 解决方案
CA_ERROR 请求未携带证书,或请求携带的证书出错 到商户平台下载证书,请求带上证书后重试。
SIGN_ERROR 商户签名错误 按文档要求重新生成签名后再重试。
NO_AUTH 没有权限 请联系微信支付开通api权限。
FREQ_LIMIT 受频率限制 请对请求做频率控制
XML_ERROR 请求的xml格式错误,或者post的数据为空 检查请求串,确认无误后重试
PARAM_ERROR 参数错误 请查看err_code_des,修改设置错误的参数
OPENID_ERROR Openid错误 根据用户在商家公众账号上的openid,获取用户在红包公众账号上的openid 错误。请核对商户自身公众号appid和用户在此公众号下的openid。
NOTENOUGH 余额不足 商户账号余额不足,请登录微信支付商户平台充值
FATAL_ERROR 重复请求时,参数与原单不一致 使用相同商户单号进行重复请求时,参数与第一次请求时不一致,请检查并修改参数后再重试。
TIME _LIMITED 企业红包的发送时间受限 请北京时间0:00-8:00时间之外触发红包赠送
SECOND_OVER_LIMITED 企业红包的按分钟发放受限 每分钟发送红包数量不得超过1800个;(可联系微信支付wxhongbao@tencent.com调高额度)
DAY_ OVER_LIMITED 企业红包的按天日发放受限 单个商户日发送红包数量不大于10000个;(可联系微信支付wxhongbao@tencent.com调高额度)
MONEY_LIMIT 红包金额发放限制 每个红包金额必须大于1元,小于1000元(可联系微信支付wxhongbao@tencent.com调高额度至4999元)
SEND_FAILED 红包发放失败,请更换单号再重试。 原商户单号已经失败,如果还要对同一个用户发放红包, 需要更换新的商户单号再试。
SYSTEMERROR 系统繁忙,请再试。 可用同一商户单号再次调用,只会发放一个红包。

签名算法

第一步,设所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA。

特别注意以下重要规则: 参数名ASCII码从小到大排序(字典序); 如果参数的值为空不参与签名; 参数名区分大小写; 验证调用返回或微信主动通知签名时,传送的sign参数不参与签名,将生成的签名与该sign值作校验。

第二步,在stringA最后拼接上key=商户支付密钥得到stringSignTemp字符串,并对stringSignTemp进行MD5运算,再将得到的字符串所有字符转换为大写,得到sign值signValue。

举例:
假设传送的参数如下:
appid: wxd930ea5d5a258f4f
mch_id: 10000100
device_info: 1000
Body: test
nonce_str: ibuaiVcKdpRxkhJA
第一步:对参数按照key=value的格式,并按照参数名ASCII字典序排序如下:stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";
第二步:拼接支付密钥:
stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
最终得到最终发送的数据:
<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>

生成随机数算法

微信支付API接口协议中包含固定nonce_str,主要保证签名不可预测。我们推荐生成随机数算法如下:

调用随机数生成函数,将得到的值转换为字符串。

商户证书

  1. 获取商户证书

微信支付接口中,涉及资金回滚的接口会使用到商户证书,包括退款、撤销接口。商家在申请微信支付成功后,收到的相应邮件通知中,附件会包含接口需要用到的证书文件,有四个证书文件,分别说明如下。

证书文件说明:

证书附件 描述 使用场景 备注
pkcs12格式(apiclient_cert.p12) 包含了私钥信息的证书文件,为p12(pfx)格式,由微信支付签发给您用来标识和界定您的身份 撤销、退款申请API中调用 windows上可以直接双击导入系统,导入过程中会提示输入证书密码,证书密码默认为您的商户ID(如:10010000)
证书pem格式(apiclient_cert.pem) 从apiclient_cert.p12中导出证书部分的文件,为pem格式,请妥善保管不要泄漏和被他人复制 PHP等不能直接使用p12文件,而需要使用pem,为了方便您使用,已为您直接提供 您也可以使用openssl命令来自己导出:openssl pkcs12 -clcerts -nokeys -in apiclient_cert.p12 -out apiclient_cert.pem
证书密钥pem格式(apiclient_key.pem) 从apiclient_cert.p12中导出密钥部分的文件,为pem格式 PHP等不能直接使用p12文件,而需要使用pem,为了方便您使用,已为您直接提供 您也可以使用openssl命令来自己导出:openssl pkcs12 -nocerts -in apiclient_cert.p12 -out apiclient_key.pem
CA证书(rootca.pem) 微信支付api服务器上也部署了证明微信支付身份的服务器证书,您在使用api进行调用时也需要验证所调用服务器及域名的真实性 该文件为签署微信支付证书的权威机构的根证书,可以用来验证微信支付服务器证书的真实性 部分工具已经内置了若干权威机构的根证书,无需引用该证书也可以正常进行验证,这里提供给您在未内置所必须根证书的环境中载入使用
  1. 使用商户证书

apiclient_cert.p12是商户证书文件,除PHP外的开发均使用此证书文件。 商户如果使用.NET环境开发,请确认Framework版本大于2.0,必须在操作系统上双击安装证书apiclient_cert.p12后才能被正常调用。 商户证书调用或安装都需要使用到密码,该密码的值为微信商户号(mchid) PHP开发环境请使用商户证书文件apiclient_cert.pem和apiclient_key.pem ,rootca.pem是CA证书。

  1. 商户证书安全

证书文件放在非web服务器虚拟目录的文件夹下,防止被他人下载。商户服务器要做好病毒和木马防护工作,不被非法侵入者窃取证书文件。