微信开放文档

接口说明

设置单个红包的金额，类型等，生成红包信息。预下单完成后，需要在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，主要保证签名不可预测。我们推荐生成随机数算法如下：

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

商户证书

获取商户证书

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

证书文件说明：

证书附件	描述	使用场景	备注
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进行调用时也需要验证所调用服务器及域名的真实性	该文件为签署微信支付证书的权威机构的根证书，可以用来验证微信支付服务器证书的真实性	部分工具已经内置了若干权威机构的根证书，无需引用该证书也可以正常进行验证，这里提供给您在未内置所必须根证书的环境中载入使用

使用商户证书

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

商户证书安全

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