API Description

This API is used to set the amount, type and other information of a red packet. After the red packet is pre-ordered, it needs to be drawn by a user in the campaign by calling JSAPI within 72 hours. (Upon its expiration, the money is returned to the merchant's TenPay account.)

API Request Format

API request from server
HTTP request method: POST<a href="https://api.mch.weixin.qq.com/mmpaymkttransfers/hbpreorder" target="_blank">https://api.mch.weixin.qq.com/mmpaymkttransfers/hbpreorder</a>

POST data format: XML
Merchant certificate is required.

Request Parameters

Parameter Field Required Example Type Description
Random String nonce_str Yes 5K8264ILTKCH16CQ2502SI8Z NMTM67VS String(32) Random string not longer than 32 digits
Signature sign Yes C380BEC2BFD727A4B68451335 19F3AD6 String(32) For more information on how to generate a signature, see "Signature Algorithm".
Merchant Order No. mch_billno Yes 10000098201411111234567890 String(28) Each merchant order No. must be unique. Format of order No.: mch_id+yyyymmdd+a 10-digit number that cannot be duplicated in one day. The API supports re-entry of merchant order No. and can be called again if a timeout occurs.
Merchant ID mch_id Yes 10000098 String(32) ID of the merchant who provides the red packet (the merchant ID assigned by WeChat Pay)
Official Account appid wxappid Yes wx8888888888888888 String(32) Appid of the Official Account owned by the red packet provider. The profile photo is displayed on the red packet page.
Merchant Name send_name Yes Rainbow Shopping Mall String(32) Name of the merchant who provides the red packet. The name is displayed on the red packet page.
Red Packet Type hb_type Yes NORMAL String(16) NORMAL-common red packet; GROUP-sharable red packet (which can be shared to friends, and does not lead users to following an Official Account.
Total Amount total_amount Yes 1000 int Total payment amount (in cents)
Number of Red Packet Recipients total_num Yes 1 int Total number of red packet recipients (including the sharers). Enter 1 for common red packets, and enter a value greater than 1 for sharable red packets.
Red Packet Amount Setting Method amt_type Yes ALL_RAND String(32) The red packet amount setting method. This is only applicable to sharable red packets. ALL_RAND - Random amount for all packets.
Red Packet Greetings wishing Yes Thank you for participating in the riddle guessing. Happy Lantern Festival! String(16) Greetings displayed on the red packet page
Campaign Name act_name Yes Guess riddles to get red packets String(32) Campaign name. It is displayed in the red packet message in Weixin version that does not support native red packets.
Remarks remark Yes Guess more to get more red packets! String(32) Remarks. It is displayed in the red packet message in Weixin version that does not support native red packets.
Authorized Merchant ID auth_mchid Yes 1000052601 String(32) This ID is used by WeChat Pay for identifying Shake-Nearby red packets during issuance of red packets. All developers need to enter the merchant ID of the Shake-Nearby platform: 1000052601.
Authorized Merchant APPID auth_appid Yes wxbf42bd79c4391863 String(32) This ID is used by WeChat Pay for identifying Shake-Nearby red packets during issuance of red packets. All developers need to enter the appid of the Shake-Nearby platform: wxbf42bd79c4391863.
Risk Control Settings risk_cntl Yes NORMAL String(32) This parameter is used to manage API risks. NORMAL: normal; IGN_FREQ_LMT - forced issuance of red packets by ignoring anti-cheating restriction; IGN_DAY_LMT - forced issuance of red packets by ignoring daily amount limit for a user; IGN_FREQ_DAY_LMT - forced issuance of red packets by ignoring anti-cheating restriction and daily amount limit for a user. Set to NORMAL if no special requirement exists. Ignoring a risk control may cause your loss of funds.

Request Example

<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[Wish You Prosperity ]]></wishing>    
<act_name><![CDATA[ Red Packets for New Year ]]></act_name>     
<remark><![CDATA[Red Packets for New Year ]]></remark>     
<risk_cntl><![CDATA[NORMAL]]></risk_cntl>     
<nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str>
</xml>

Response

The response data is in an XML format.

Parameter Field Required Example Type Description
Response Status Code return_code Yes SUCCESS String(16) SUCCESS/FAIL; This field indicates the request result, instead of transaction result. Result_code indicates whether the transaction is successful.
Response Message return_msg No Signature failed String(128) The response message indicates the error reason (signature failure, incorrect parameter format) if it is a non-null value.

The following fields are returned when return_code is SUCCESS.

Parameter Field Required Example Type Description
Signature sign Yes C380BEC2BFD727A4B6845133519F3AD6 String(32) For more information on how to generate a signature, see "Signature Algorithm".
Business Result result_code Yes SUCCESS String(16) SUCCESS/FAIL
Error Code err_code No SUCCESS String(32) Error code information
Error Description err_code_des No System error String(128) Result description

The following fields are returned when both return_code and result_code are SUCCESS.

Parameter Field Required Example Type Description
Merchant Order No. mch_billno Yes 10000098201411111234567890 String(28) Each merchant order No. must be unique. Format of order No.: mch_id+yyyymmdd+a 10-digit number that cannot be duplicated in one day.
Merchant ID mch_id Yes 10000098 String(32) The merchant ID assigned by WeChat Pay
Official Account appid wxappid Yes wx8888888888888888 String(32) Merchant appid
Total Amount total_amount Yes 1000 int Total payment amount (in cents)
ticket sp_ticket Yes 2J6MtR+SlbZ8Ga4EDi64X5 vC4Xv01ofX4uWOqqTc9kGJYhkq5 st5ucrXKxkjnC/UuvLeuhdIfiYg i4hJuJ95qjt9mwxqSBEmjGbZlL+ sqM9upoWsEjup28KPvaVrdao/Hg 6WqyqUL5E2zPHfM1sb1w== String Sp_ticket. A common red packet has one ticket.
Red Packet Order No. detail_id Yes 0000000666201504290000042120 Red packet's internal order No.
Issuance Time Yes 20150429203444 Issuance time of red packet

Successful Transaction Example

<xml> 
<return_code><![CDATA[SUCCESS]]></return_code> 
<return_msg><![CDATA[Issued successfully.]]></return_msg> 
<result_code><![CDATA[SUCCESS]]></result_code> 
<err_code><![CDATA[0]]></err_code> 
<err_code_des><![CDATA[Issued successfully.]]></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>

Failed Transaction Example

<xml>     
<return_code><![CDATA[FAIL]]></return_code> 
<return_msg><![CDATA[System is busy. Try again later..]]></return_msg> 
<result_code><![CDATA[FAIL]]></result_code> 
<err_code><![CDATA[268458547]]></err_code> 
<err_code_des><![CDATA[System is busy. Try again later..]]></err_code_des> 
<mch_billno><![CDATA[0010010404201411170000046542]]></mch_billno>        
<mch_id>10010404</mch_id> 
<wxappid><![CDATA[wx6fa7e3bab7e15415]]></wxappid> 
<total_amount>3</total_amount> 
</xml>

Error Codes

Error Code Description Solution
CA_ERROR No certificate contained in the request, or an error occurred with the certificate contained in the request. Go to the Merchants Platform to download the certificate, contain the certificate in the request, and try again.
SIGN_ERROR Incorrect merchant signature Regenerate the signature as described by the documentation and try again.
NO_AUTH No permission Contact WeChat Pay to activate the api permission.
FREQ_LIMIT Request rate exceeded the limit Reduce the request rate
XML_ERROR Incorrect XML format of request, or the data sent using Post method is null. Check the request string, and try again
PARAM_ERROR Incorrect parameter Check err_code_des to modify the incorrect parameter.
OPENID_ERROR Incorrect openid The user's openid under the red packet Official Account does not match that under the merchant's Official Account. Check the merchant's Official Account appid and the user's openid under the Official Account.
NOTENOUGH Insufficient balance Insufficient balance on merchant account. Log in to the WeChat Pay Merchants Platform to top up the account.
FATAL_ERROR The parameters for the second request do not match those for the first request If a second request is made using the same merchant order No., but its parameters do not match those for the first request, check and correct the parameters, and then try again.
TIME _LIMITED The company red packets were issued in the disallowed time period. Issue the red packets outside Beijing Time 0:00-8:00.
SECOND_OVER_LIMITED The number of company red packets issued per minute exceeded the limit. A maximum of 1,800 red packets can be issued per minute. (contact WeChat Pay wxhongbao@tencent.com to increase the limit)
DAY_ OVER_LIMITED The number of company red packets issued per day exceeded the limit. A maximum of 10,000 red packets can be issued per day. (contact WeChat Pay wxhongbao@tencent.com to increase the limit)
MONEY_LIMIT Red packet amount exceeded the limit. The amount of each red packet must be greater than 1 CNY and less than 1,000 CNY. (Contact WeChat Pay wxhongbao@tencent.com to increase the limit to 4,999 CNY)
SEND_FAILED Red packet issuance failed. Use another order number and try again. The original merchant order number has failed. To issue a red packet to the same user, you need to use a new merchant order number and try again.
SYSTEMERROR System is busy. Try again. Call the API again using the same merchant order number. Only one red packet will be issued.

Signature Algorithm

Step 1: Create a Set M consisting of all the data sent or received. Sort the non-null parameters in Set M in an ascending lexicographical order by parameter name ASCII code, and then join the parameters into stringA in the URL key-value format (key1=value1&key2=value2…).

Notes: The parameter name ASCII codes are sorted in an ascending lexicographical order; Any parameter with a null value is excluded from the signature; Parameter names are case sensitive; When the response is verified or Weixin notifies the signature, the transferred "sign" parameter is not involved in the signature, and the generated signature is verified with the "sign" value.

Step 2: Obtain the stringSignTemp by appending "key=merchant's payment key" to stringA, and perform MD5 operation on stringSignTemp. Then convert all the characters of the resulting string into uppercase to obtain the signValue.

Example:
Assuming that the following parameters are transferred:
appid:  wxd930ea5d5a258f4f
mch_id:  10000100
device_info:  1000
Body:  test
nonce_str:  ibuaiVcKdpRxkhJA
Step 1: Sort the parameters in an ascending lexicographical order by parameter name ASCII code in a format of key=value: stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";
Step 2: Join the stringA with the payment key:
stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
Get the final data for sending:
<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>

Random Number Generation Algorithm

WeChat Pay API protocol includes a fixed nonce_str, which guarantees that the signature is unpredictable. We recommend the following random number generation algorithm:

Call the random number generation function to convert the value obtained into a string.

Merchant Certificate

  1. Obtaining Merchant Certificate

Merchant certificate is required for the WeChat Pay APIs involving the rollback of funds, including the Refund and Cancellation APIs. When a merchant successfully applies for WeChat Pay permission, the merchant receives the following four certificate files in the attachment to the email notification:

Description of certificate files:

Certificate Description Use Case Remarks
Certificate file in pkcs12 format (apiclient_cert.p12) A certificate file containing private key information in p12 (pfx) format. It is issued by WeChat Pay for you to identify and define your identity Used by Refund and Cancellation APIs Double-click the certificate on Window OS to directly import it. When prompted to enter the certificate password, enter your merchant ID (such as 10010000) by default.
Certificate file in pem format (apiclient_cert.pem) The certificate file exported from apiclient_cert.p12 in a pem format. Be sure to keep it secure to avoid leakage or unauthorized access. For development in PHP, only a .pem file, instead of a .p12 file, is supported. The .pem file has been made ready for your use. You can also export the file yourself using openssl command: openssl pkcs12 -clcerts -nokeys -in apiclient_cert.p12 -out apiclient_cert.pem
Certificate key file in pem format (apiclient_key.pem) The key file exported from apiclient_cert.p12 in a pem format. For development in PHP, only a .pem file, instead of a .p12 file, is supported. The .pem file has been made ready for your use. You can also export the file yourself using openssl command: openssl pkcs12 -nocerts -in apiclient_cert.p12 -out apiclient_key.pem
CA certificate (rootca.pem) The server certificate identifying the WeChat Pay identity is also deployed on the WeChat Pay API server. You also need to verify the authenticity of the server and domain name when you use the API. This is the root certificate issued by the CA which signs the WeChat Pay certificate, and can be used to verify the authenticity of the WeChat Pay server certificate Some tools already come with the root certificates from several CAs, so verification can be performed without importing this certificate. If the root certificate required is not built in your environment, you may use this certificate.
  1. Using Merchant Certificate

Apiclient_cert.p12 is a merchant certificate file, which is used in a development environment in any language other than PHP. A merchant using the .NET environment needs to ensure the Framework version is above 2.0. You must double-click the installation certificate apiclient_cert.p12 on the operating system to invoke it normally. A password is required for invoking and installing a merchant certificate. The password is the Weixin merchant ID (mchid). In a PHP development environment, use the merchant certificate file apiclient_cert.pem and apiclient_key.pem. Rootca.pem is the root certificate from CA.

  1. Merchant Certificate Security

The certificate files should be placed in a folder of the virtual directory on a non-Web server to prevent unauthorized download. It is recommended to take precautions to prevent the merchant server against viruses, Trojans and hacking by hackers.