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
- 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. |
- 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.
- 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.