Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Submit Quick Pay API

Latest update time:2019.11.30 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.

Tips:

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.

API intro

Request Url:https://api.mch.weixin.qq.com/pay/micropay

Request method:POST

Certificate Requirements:No certificate is required.

Applicable object:Common modeInstitutional mode

Parameter Settings

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" }

Here is the sample code:


<xml>
   <appid>wx2421b1c4370ec43b</appid>
   <attach>Additional Order Descriptionr</attach>
   <auth_code>120269300684844649</auth_code>
   <body>Quick Pay Testing</body>
   <device_info>1000</device_info>
   <goods_tag></goods_tag>
   <mch_id>10000100</mch_id>
   <nonce_str>8aaee146b1dee7cec9100add9b96cbe2</nonce_str> 
   <detail><![CDATA[{"goods_detail":[{"wxpay_goods_id":"1001"}]}]]></detail>
   <out_trade_no>1415757673</out_trade_no>
   <spbill_create_ip>14.17.22.52</spbill_create_ip>
   <total_fee>1</total_fee>
   <sign>C29DB7DB1FD4136B84AE35604756362C</sign>
</xml>                  
    
{
JAVA示例代码
}
    

Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.

Return Data

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

Example:


<xml>
   <return_code><![CDATA[SUCCESS]]></return_code>
   <return_msg><![CDATA[OK]]></return_msg>
   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
   <mch_id><![CDATA[10000100]]></mch_id>
   <device_info><![CDATA[1000]]></device_info>
   <nonce_str><![CDATA[GOp3TRyMXzbMlkun]]></nonce_str>
   <sign><![CDATA[D6C76CB785F07992CDE05494BB7DF7FD]]></sign>
   <result_code><![CDATA[SUCCESS]]></result_code>
   <openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
   <is_subscribe><![CDATA[Y]]></is_subscribe>
   <trade_type><![CDATA[MICROPAY]]></trade_type>
   <bank_type><![CDATA[CCB_DEBIT]]></bank_type>
   <total_fee>1</total_fee> 
   <fee_type><![CDATA[CNY]]></fee_type>
   <transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
   <out_trade_no><![CDATA[1415757673]]></out_trade_no>
   <attach><![CDATA[Additional order description]]></attach>
   <time_end><![CDATA[20141111170043]]></time_end>
</xml> 

Error Codes

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.

Release notes

关闭
V1.0
2019.11.20
1. Submit Quick Pay API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2019 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

Wechat Pay Global

ICP证

粤B1.B2-20090295