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

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

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

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

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.