红包预下单接口

接口说明

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

接口调用说明

服务器端调用
http请求方式: POST
https://api.mch.weixin.qq.com/mmpaymkttransfers/hbpreorder

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

请求参数说明

参数字段是否必须示例值类型说明
随机字符串nonce_str5K8264ILTKCH16CQ2502SI8Z

NMTM67VS

String(32)随机字符串,不长于32位
签名signC380BEC2BFD727A4B68451335

19F3AD6

String(32)生成签名方式查看签名算法
商户订单号mch_billno10000098201411111234567890String(28)商户订单号(每个订单号必须唯一)组成: mch_id+yyyymmdd+10位一天内不能重复的数字。接口根据商户订单号支持重入, 如出现超时可再调用。
商户号mch_id10000098String(32)红包提供者的商户号(微信支付分配的商户号)
公众账号appidwxappidwx8888888888888888String(32)红包提供者公众号的appid,对应头像展示在红包页面
商户名称send_name天虹百货String(32)红包提供者名称,展示在红包页面
红包类型hb_typeNORMALString(16)NORMAL-普通红包;GROUP-裂变红包(可分享红包给好友,无关注公众号能力)。
总金额total_amount1000int总付款金额,单位分
红包发放总人数total_num1int红包发放总人数,即总共有多少人可以领到该组红包(包括分享者)。普通红包填1,裂变红包必须大于1。
红包金额设置方式amt_typeALL_RANDString(32)红包金额设置方式,只对裂变红包生效。ALL_RAND—全部随机
红包祝福语wishing感谢您参加猜灯谜活动,祝您元宵节快乐String(16)红包祝福语,展示在红包页面
活动名称act_name猜灯谜抢红包活动String(32)活动名称,在不支持原生红包的微信版本中展示在红包消息
备注remark猜越多得越多,快来抢!String(32)备注信息,在不支持原生红包的微信版本中展示在红包消息
授权商户号auth_mchid1000052601String(32)用于发红包时微信支付识别摇周边红包,所有开发者统一填写摇周边平台的商户号:1000052601
授权商户APPIDauth_appidwxbf42bd79c4391863String(32)用于发红包时微信支付识别摇周边红包,所有开发者统一填写摇周边平台的appid:wxbf42bd79c4391863
风控设置risk_cntlNORMALString(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_codeSUCCESSString(16)SUCCESS/FAIL;此字段是通信标识,非交易标识,交易是否成功需要查看result_code来判断
返回信息return_msg签名失败String(128)返回信息,如非空,为错误原因 签名失败 参数格式校验错误  

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

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

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

参数字段是否必须示例值类型说明
商户订单号mch_billno10000098201411111234567890String(28)商户订单号(每个订单号必须唯一)组成: mch_id+yyyymmdd+10位一天内不能重复的数字。
商户号mch_id10000098String(32)微信支付分配的商户号
公众账号appidwxappidwx8888888888888888String(32)商户appid
总金额total_amount1000int总付款金额,单位分
ticketsp_ticket2J6MtR+SlbZ8Ga4EDi64X5

vC4Xv01ofX4uWOqqTc9kGJYhkq5 st5ucrXKxkjnC/UuvLeuhdIfiYg i4hJuJ95qjt9mwxqSBEmjGbZlL+ sqM9upoWsEjup28KPvaVrdao/Hg 6WqyqUL5E2zPHfM1sb1w==

Stringsp_ticket,一个普通红包对应一个ticket
红包订单号detail_id0000000666201504290000042120
红包内部订单号
发送时间
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_ERROROpenid错误根据用户在商家公众账号上的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进行调用时也需要验证所调用服务器及域名的真实性该文件为签署微信支付证书的权威机构的根证书,可以用来验证微信支付服务器证书的真实性部分工具已经内置了若干权威机构的根证书,无需引用该证书也可以正常进行验证,这里提供给您在未内置所必须根证书的环境中载入使用   

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服务器虚拟目录的文件夹下,防止被他人下载。商户服务器要做好病毒和木马防护工作,不被非法侵入者窃取证书文件。