Latest update time：2021.12.21 Release notes
After the Cashier scans a bar or QR code on the Quick Pay page shown by the Payer, the payment parameters are transferred to the Merchant’s backend. The Merchant’s backend calls the Submit Quick Pay API to initiate a payment.
1. Trade result will be returned synchronously. Query Order API should be called 5s later if it returns “System error”. This API is also required once it returns “USERPAYING”, and it should be called continuously until the payment is successful or timeout (advised timeout time is 30s, advised calling frequency is 10s once).
2. Please revoke the order if it returns an uncertain trade status when calling Query Order API. After revoking, the successful order will be refunded, while the failed order will be closed. Please call again if it returns failed when calling Revoke Order API. Please notice that Revoke Order API should be called at least 15s later after the order is created, and it requires passing the certificate.
3. In this payment mode, if the payment amount is less than 3000 RMB or the number of payments on the day is less than 10 times, the request will be deducted directly without requiring the user to enter a password. If any of the above conditions are not met, the user will be required to enter a password to verify the deduction.
Request Url:https://api.mch.weixin.qq.com/pay/micropay
Request method:POST
Certificate Requirements：No certificate is required.
Applicable object:Common modeInstitutional mode
| Name | ID | Type | Required | Description |
|---|---|---|---|---|
| Official Account ID | appid | string(32) | Yes | Specifies an Official Account ID assigned by WeChat Example：wx8888888888888888 |
| Merchant ID | mch_id | string(32) | Yes | Specifies merchant ID assigned by WeChat Payment Example：1900000109 |
| Sub Official Account ID | sub_appid | string(32) | No | Specifies an Sub Official Account ID assigned by WeChat Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：wx8888888888888888 |
| Sub Merchant ID | sub_mch_id | string(32) | Yes | Specifies Sub merchant ID assigned by WeChat Payment Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：1900000109 |
| Device ID | device_info | string(32) | No | Specifies a Terminal device ID (such as store number as defined by the merchant) Example：013467007045764 |
| Random string | nonce_str | string(32) | Yes | 32 characters or fewer. For more information, see Random string Algorithm . Example：5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| Signature | sign | string(64) | Yes | For more information, see Signature Algorithm. Example：C380BEC2BFD727A4B6845133519F3AD6 |
| Sign type | sign_type | string(32) | NO | Currently HMAC-SHA256 and MD5 are supported, default is MD5. This parameter must be submitted if HMAC-SHA256 is chosen Example：HMAC-SHA256/MD5 |
| Item Description | body | string(128) | Yes | Please refer to Item Description Example：Pay for QQ Coins |
| Version ID | version | string(32) | Yes | Fixed value: 1.0 Example：1.0 |
| Items Details | detail | string(6000) | Yes | Detailed mcc code described in JSON format. Please use CDATA tag to protect the JSON string when transferring data. goods_detail └ wxpay_goods_id string Required 32 Note: MCC code is now required when calling payment APIs. Please refer to , part 7 for the MCC code list. And please refer to the samples of how to transfer the mcc code. Example：{"goods_detail":[{ "wxpay_goods_id ":"1001"}]} |
| Additional Data | attach | string(128) | No | Allow merchants an additional field to be returned in the payment notification after submitting a payment to the Query Order API Example：User-Defined Data |
| Merchant Order Number | out_trade_no | string(32) | Yes | 32 alphanumeric characters or less. For more information, see Merchant's Order Number. Example：1217752501201407033233368018 |
| Bid price | total_fee | int | Yes | Specifies the total order amount. The units are expressed in cents as integers. For more details, see Payment Amount. Example：888 |
| Currency Type | fee_type | string(16) | Yes | ISO-4217 standard compliant and be described by three characters based code. For more information, see Currency Type. Note: This field could be set as settlement currency type of mch_id or CNY. part 1 for the settlement currency types. Example：USD |
| Terminal IP | spbill_create_ip | string(64) | Yes | Specifies the machine IP that calls the WeChat Payment API Note: Both IPv4 and IPv6 are supported. Example：8.8.8.8 |
| Item Label | goods_tag | string(32) | No | Specifies the label of goods, which is a parameter in the coupon feature for businesses. |
| Authorization Code | auth_code | string(128) | Yes | Specifies the authorization code for scanning a barcode/QR Code on Quick Pay Note: The WeChat barcodes are constructed with 18 numbers, with the start value of 10, 11, 12, 13, 14 or 15. Barcodes with 10-14 are for the China mainland users, while barcodes with 15 are for the China Hong Kong users, who cannot use WeChat cross-border pay. Example：120061098828009406 |
| Transaction Start Time | time_start | string(14) | No | Specifies the transaction creation time in the format yyyyMMddHHmmss, such as 20091225091010 for Dec 25, 2009 09:10:10 (UTC+08). For more information, see Time Protocol. Example：20091225091010 |
| Transaction End Time | time_expire | string(14) | No | Specifies the transaction end time in the format yyyyMMddHHmmss, such as 20091227091010 for Dec 27, 2009 09:10:10 (UTC+08). For more information, see Time Protocol. Example：20091227091010 |
| Scenarios Information | scene_info | string(256) | No | Specify the payment scenarios, such as the store or mall information. { “store_id”:””, //Unique ID of store, Optional, string(32) “store_name”:””//Store name, Optional, string(64) } Example：{ "store_id": "SZT10000", "store_name":"Dining Hall of Tencent Mansion" } |
<xml>
<appid>wx2421b1c4370ec43b</appid>
<body>An apple</body>
<attach>Additional Order Descriptionr</attach>
<device_info>123001</device_info>
<auth_code>134539517967686076</auth_code>
<fee_type>EUR</fee_type>
<mch_id>10000100</mch_id>
<nonce_str>f6868b9b16bf4893958afd4a46d73422</nonce_str>
<out_trade_no>2017101418207317</out_trade_no>
<detail><![CDATA[{"goods_detail":[{"wxpay_goods_id":"1001","goods_name":"iPhone6s 32G","quantity":1}]}]]></detail>
<sign>5F244D7C69241AB7BC937A7A2A542294</sign>
<sub_mch_id>452532745</sub_mch_id>
<total_fee>1</total_fee>
</xml>
Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.
| Name | ID | Type | Required | Description |
|---|---|---|---|---|
| Return Status Code | return_code | string(16) | Yes | Set to SUCCESS or FAIL Specifies communicating label instead of transaction label. The status of the transaction is determined by the value of the result_code field. Example：SUCCESS |
| Return Data | return_msg | string(128) | No | If not empty, this is the error description. If not empty, this is the error description Signature Failure Parameter format checking error Example：Signature Failure |
When return_code is SUCCESS, return data will also include the following fields:
| Name | ID | Type | Required | Description |
|---|---|---|---|---|
| Official Account ID | appid | string(32) | Yes | The Official Account ID submitted when calling the interface Example：wx8888888888888888 |
| Merchant ID | mch_id | string(32) | Yes | The Merchant ID submitted when calling the interface Example：1900000109 |
| Sub Official Account ID | sub_appid | string(32) | No | The Sub Official Account ID submitted when calling the interface Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：wx8888888888888888 |
| Sub Merchant ID | sub_mch_id | string(32) | Yes | The Sub Merchant ID submitted when calling the interface Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：1900000109 |
| Device ID | device_info | string(32) | No | Specifies the ID of the terminal device with from which the Merchant submitted their order Example：013467007045764 |
| Random string | nonce_str | string(32) | Yes | 32 characters or fewer Example：Fsdfds1235df231asdfg32145gfdse |
| Signature | sign | string(64) | Yes | Specifies a signature. For more information, see Signature Algorithm Example：C380BEC2BFD727A4B6845133519F3AD6 |
| Service Result | result_code | string(16) | Yes | Set to SUCCESS or FAIL Example：SUCCESS |
| Error Code | err_code | string(32) | No | Please refer to Error Codes Example：SYSTEMERROR |
| Error Code Description | err_code_des | string(128) | No | The detailed description of error Example：System error |
When return_code and result_code are SUCCESS, return data will also include the following fields:
| Name | ID | Type | Required | Description |
|---|---|---|---|---|
| User Tag | openid | string(128) | Yes | It is the only user identification under the current appid Example：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| Follows Official Account or not | is_subscribe | string(1) | Yes | For users who pay for transactions related to an official account, the value in this field states whether the user is current following the official account Y: Follows N: Doesn’t follow Example：Y |
| Sub User Tag | sub_openid | string(128) | No | It is the only user identification under the current sub appid Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o |
| Follows Sub Official Account or not | sub_is_subscribe | string(1) | Yes | For users who pay for transactions related to an sub official account, the value in this field states whether the user is current following the official account Y: Follows N: Doesn’t follow Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：Y |
| Transaction Type | trade_type | string(16) | Yes | The transaction type is MICROPAY(quick pay) Example：MICROPAY |
| Payment Bank | bank_type | string(32) | Yes | strings states bank type Example：CMC |
| Currency Type | fee_type | string(16) | Yes | Complies with ISO 4217 standards and uses 3 characters based code. For more information, see Currency Type. Example：USD |
| Total Amount | total_fee | int | Yes | Specifies the total amount for a transaction. The unit is cent and the value must be integer. For more information, see Payment Amount. Example：100 |
| Cash Type | cash_fee_type | string(16) | Yes | Complies with ISO 4217 standards and uses CNY (Chinese yuan) by default. For more information, see Currency Type. Example：CNY |
| Cash Payment Amount | cash_fee | int | Yes | Specifies the total cash payment amount of a transaction. For more information, see Payment Amount. Example：100 |
| WeChat Payment Order Number | transaction_id | string(32) | Yes | Specifies the WeChat payment order id Example：1217752501201407033233368018 |
| Merchant Order Number | out_trade_no | string(32) | Yes | Specifies the order number created within the Merchants' system, which is consistent with request. Example：1217752501201407033233368018 |
| Merchant's Data Package | attach | string(128) | No | Specifies merchant's data package, which is returned as it is. Example：123456 |
| Payment End Time | time_end | string(14) | Yes | Specifies transaction creation time in the format of yyyyMMddHHmmss, such as 20091225091010 for Dec 25, 2009 09:10:10. For more information, see Time Protocol. Example：20141030133525 |
| Exchange Rate | rate | string(16) | Yes | The value is 10 to the 8th power times of the exchange rate from foreign currency to RMB. For example, the exchange rate from foreign currency to RMB is 6.5, the value will be 650000000 Example：650000000 |
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<result_code><![CDATA[FAIL]]></result_code>
<err_code_des><![CDATA[需要用户输入支付密码]]></err_code_des>
<err_code><![CDATA[USERPAYING]]></err_code>
<mch_id><![CDATA[10000100]]></mch_id>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<sub_mch_id><![CDATA[452532745]]></sub_mch_id>
<device_info><![CDATA[123001]]></device_info>
<nonce_str><![CDATA[EBObtckqDbde2wll]]></nonce_str>
<sign><![CDATA[E0635D8F665727ACE62DEF430C22B9A4]]></sign>
</xml>
| Name | Description | Reason | Solution |
|---|---|---|---|
| SYSTEMERROR | API return error | System timed out | Call the Query Order API immediately to check the current status, and use the returned status to decide the next steps for processing the order. |
| PARAM_ERROR | Parameter error | Requested parameters are not correct | Debug your program based on data returned by the API |
| ORDERPAID | Order is paid | Duplicate order number | Confirm whether this order has already been processed. If not, submit it as a new order. |
| NOAUTH | No permissions for merchants | Merchants hasn’t enabled Quick Pay | Apply and receive permission to use Quick Pay first. For applying for this payment method, contact customer service. |
| AUTHCODEEXPIRE | QR Code expired. Refresh and try again. | Payer's bar code has expired | Cashier should ask payer to refresh the bar code/QR code on WeChat and scan the code again. This error is displayed directly to the cashier. |
| NOTENOUGH | Insufficient balance | Payer has insufficient balance in their payment account | Cashiers should inform the payer to change their payment bank card and scan it again. Note: In this scenario, the Cashier’s point of sale terminal should receive a message saying "Insufficient balance in this card. Try another one" from the Merchant’s backend. |
| NOTSUPORTCARD | Unsupported card type | The type of card used by the payer for their payment is not supported at the moment | Payer will receive a message in WeChat telling them to select another card type Note: In this scenario, the cashier’s point of sale terminal should receive a message saying "Unsupported card type. Try another one or link a new card for payment" from the merchant’s backend. |
| ORDERCLOSED | Order is closed | The order is closed | An exception has occurred with this transaction. Create a new order and redo the payment process. |
| ORDERREVERSED | Order is cancelled | The order is cancelled | An exception has occurred with this transaction. Create a new order and redo the payment process. |
| BANKERROR | Bank system exceptions | Bank system timed out | Call the Query Order API immediately and check the current transaction status. Process the next steps based on this status. |
| USERPAYING | Password is required as payers are making their payment | This transaction requires payment password | Wait for 5 seconds and then call the Query Order API again to check current transaction status. Process the next steps based on this status. |
| AUTH_CODE_ERROR | Authorization parameter error | Requested parameters are not correct | Each QR code can only be used once. Payer should refresh the QR code and try again. |
| AUTH_CODE_INVALID | Authorization code checking error | The bar or QR code scanned by cashiers is not the one on the Quick Pay page | Scan bar or QR code on the Quick Pay page |
| XML_FORMAT_ERROR | Invalid XML format | Invalid XML format | Check whether XML parameters are in the correct format |
| REQUIRE_POST_METHOD | Use post method | Data not transferred via POST method | Check whether data is submitted via POST method |
| SIGNERROR | Signature error | Incorrect signature result | Check whether the signature parameter and method comply with signature algorithm requirements |
| LACK_PARAMS | Missing parameter | Required parameter is missing | Check whether all required parameters are complete |
| NOT_UTF8 | Invalid coding format | Specified coding format is not used | Use NOT_UTF8 encoding format |
| BUYER_MISMATCH | Incorrect payment account | Only one payer is allowed to pay for one transaction. | Check whether the payer is the same person |
| APPID_NOT_EXIST | APPID does not exist | No APPID in this parameter | Check whether provided APPID is correct |
| MCHID_NOT_EXIST | MCHID does not exist | No MCHID in this parameter | Check whether provided MCHID is correct |
| OUT_TRADE_NO_USED | Duplicate merchant order number | The same transaction can't be submitted repeatedly | Check whether the Merchant's order number has already been submitted or used previously |
| APPID_MCHID_NOT_MATCH | appid does not match mch_id | appid does not match mch_id | Check whether appid belongs to the associated mch_id |
| TRADE_ERROR | Business errors | Business error caused transaction failure | Please check whether the user’s account is normal or blocked by risk controls. |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证