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.
Query parameter needs to be passed in the request URL.
Body parameter needs to be passed in the request JSON.
2. Request Parameters
Name
Variable Name
Type
Required
Description
APPID
appid
string[1,32]
Yes
Body APPID corresponding to the Service Account applied for by the merchant on the WeChat Official Accounts Platform Note:Only for Common mode Example: wx8888888888888888
Merchant ID
mchid
string[1,32]
Yes
Body Merchant ID assigned by WeChat Pay Note:Only for Common mode Example: 1900000109
Organization APPID
sp_appid
string[1,32]
Yes
Body APPID corresponding to the Service Account applied for by the institution on the WeChat Official Accounts Platform Note:Only for Institutional mode Example: wx8888888888888888
Sub-merchant APPID
sub_appid
string[1,32]
No
Body APPID corresponding to the Service Account applied for by the sub-merchant on the WeChat Official Accounts Platform Note:Only for Institutional mode Example: wx8888888888888888
Institution's Merchant ID
sp_mchid
string[1,32]
Yes
Body Institution's Merchant ID assigned by WeChat Pay Note:Only for Institutional mode Example: 1900000109
Sub-merchant ID
sub_mchid
string[1,32]
Yes
Body Sub-merchant ID assigned by WeChat Pay Note:Only for Institutional mode Example: 1900000109
Merchant order No.
out_trade_no
string[1,32]
Yes
Body The order No. in the merchant system with a length of not more than 32 characters, including letters. If the authorization code changes, a new merchant order No. must be used. For more information, see Merchant Order No. Example: 1217752501201407033233368018
Transaction type
trade_type
string[1,16]
Yes
Body Transaction type MICROPAY：Quick Pay Example: MICROPAY
Merchant data
attach
string[1,127]
No
Body Additional data, which will be returned unchanged in the query API and payment notifications. This field is mainly used for the custom data in the orders of the merchant. Example: Custom data
Product description
description
string[1,128]
Yes
Body Brief description of the product or payment order in the following format: Name of the store brand - Name of the city branch - Name of the actual product. Example: Tencent Image Store- Shenzhen Tencent Building - QQ Doll
Product tag
goods_tag
string[1,32]
No
Body The product tag, which is a parameter for the voucher or discount feature. For more information, see Vouchers or Discounts. Example: WXG
Payment method
limit_pay
string[1,32]
No
Body no_credit: Credit card cannot be used for payment Example: no_credit
Body Payer information. For more information, see the description below.
Payer
Name
Variable Name
Type
Required
Description
Authorization code
auth_code
string[1,128]
Yes
The authorization code for QR Code Pay, that is, the code displayed when the user opens the WeChat Wallet.
Example: 120061098828009406
Order amount
amount
object
Yes
Body Information on the order amount. For more information, see the description below.
Order amount
Name
Variable Name
Type
Required
Description
Total amount
total
int
Yes
The total order amount. The minimum unit of the currency can only be an integer. For more information, see Transaction Amount.Example: 888
Currency type
currency
string[1,16]
No
Three-letter code in accordance with ISO 4217.
Example: HKD
Scenario information
scene_info
object
No
Body The scenario information object. For more information, see the description below.
Scenario information
Name
Variable Name
Type
Required
Description
Merchant's device No.
device_id
string[1,32]
No
Terminal device No. (which is customized by the merchant, such as store No.)
Example: 013467007045764
Merchant's device IP
device_ip
string[1,40]
No
The IP of the merchant's device, which is the public network egress IP and supports IPV6.
Example: 128.0.0.1
User terminal IP
payer_client_ip
string[1,40]
No
The IP of the user's device, which is the public network egress IP and supports IPV6
Example: 128.0.0.1
Operator ID
operator_id
string[1,32]
No
Cashier ID, customized by the merchant
Example: 123145
Merchants' store information
store_info
object
No
Store information object. For more information, see the description below.
Merchants' store information
Name
Variable Name
Type
Required
Description
No.
id
string[1,32]
No
Merchant store ID
Example: 0001
Name
name
string[1,32]
Yes
Merchant store name
Example: Tencent Building Branch
Address
address
string[1,64]
Yes
Detailed address of the merchant's store
Example: No. 10000, No.1, Keji Road, Science and Technology Park, Nanshan District, Shenzhen, Guangdong
Discount feature
detail
array
No
Body Discount feature info. For more information, see the description below.
Discount feature
Name
Variable Name
Type
Required
Description
Original order price
cost_price
int
No
The payment for a merchant's order may be split, and the original order price indicates the transaction amount of the entire order.
If the original order price is different from the payment amount, the discount is not available.
This field is mainly used to prevent split payment for multiple discounts. This parameter is not required for normal payment.
Example: 608800
Product receipt ID
receipt_id
string[1,32]
No
Merchant receipt ID
Example: wx123
Product details
goods_detail
array
Yes
Product details, submitted in JSON array format. See the table below.
Product details
Name
Variable Name
Type
Required
Description
Product code
goods_id
string[1,32]
Yes
It consists of a combination of uppercase and lowercase letters, numbers, hyphens and underscores.
Example: Product code
Product code on WeChat
wxpay_goods_id
string[1,32]
No
Unified product No. defined by WeChat Pay (optional)
Example: 1001
Product name
goods_name
string[1,256]
No
Actual product name
Example: iPhone6s 16G
Number of products
quantity
int
Yes
Number of products purchased by a user
Example: 1
Unit price
price
int
Yes
If the merchant provides a discount, the discounted unit price should be transferred (for example, if the user has applied a voucher of 50 CNY off 100 CNY issued by the shop to an order of 100 CNY, the discounted price should be the original 100 CNY minus 50 CNY).
Example: 528800
Request Example：
Institution Mode
1{2"sp_appid":"wxdace645e0bc2c424",3"sp_mchid":"10000100",4"sub_mchid":"20000100",5"out_trade_no":"20150806125346",6"merchant_category_code":"4111",7"payer":{8"auth_code":"134650720866361395"9},10"trade_type":"MICROPAY",11"amount":{12"total":1,13"currency":"HKD"14},15"attach":"Payment Test",16"description":"Image Store - Tencent Building in Shenzhen - QQ Doll",17"goods_tag":"1234",18"limit_pay":"no_credit",19"detail":[{20"cost_price":1,21"receipt_id":"1234",22"goods_detail":[{23"goods_id":"iphone6s_16G",24"wxpay_goods_id":"3405",25"goods_name":"iPhone6s 16G",26"quantity":1,27"price":128}]29}],30"scene_info":{31"payer_client_ip":"14.23.150.211",32"device_ip":"59.37.125.32",33"device_id":"013467007045764",34"operator_id":"P001",35"store_info":{36"id":"SZTX001",37"name":"Tencent Building Branch",38"address":"Nanshan District, Shenzhen, Guangdong"39}40}41}
Common Mode
1{2"appid":"wxdace645e0bc2c424",3"mchid":"10000100",4"out_trade_no":"20150806125346",5"merchant_category_code":"4111",6"payer":{7"auth_code":"134650720866361395"8},9"trade_type":"MICROPAY",10"amount":{11"total":1,12"currency":"HKD"13},14"attach":"Payment Test",15"description":"Image Store - Tencent Building in Shenzhen - QQ Doll",16"goods_tag":"1234",17"limit_pay":"no_credit",18"detail":{19"cost_price":1,20"receipt_id":"1234",21"goods_detail":[{22"goods_id":"iphone6s_16G",23"wxpay_goods_id":"3405",24"goods_name":"iPhone6s 16G",25"quantity":1,26"price":127}]28},29"scene_info":{30"payer_client_ip":"14.23.150.211",31"device_ip":"59.37.125.32",32"device_id":"013467007045764",33"operator_id":"P001",34"store_info":{35"id":"SZTX001",36"name":"Tencent Building Branch",37"address":"Nanshan District, Shenzhen, Guangdong"38}39}40}
3. Response Parameters
Response for successful request:
Name
Variable Name
Type
Required
Description
WeChat Pay order No.
id
string[1,32]
Yes
WeChat Pay order No. Example: 1217752501201407033233368018
APPID
appid
string[1,32]
Yes
APPID corresponding to the Service Account applied for by the merchant on the WeChat Official Accounts Platform Note:Only for Common mode Example: wx8888888888888888
Merchant ID
mchid
string[1,32]
Yes
Merchant ID assigned by WeChat Pay Note:Only for Common mode Example: 1900000109
Institution APPID
sp_appid
string[1,32]
Yes
APPID corresponding to the Service Account applied for by the institution on the WeChat Official Accounts Platform. WeChat Pay will configure the binding relationship when the institution applies for merchant features. Note:Only for Institutional mode Example: wx8888888888888888
Sub-merchant APPID
sub_appid
string[1,32]
No
APPID corresponding to the Service Account applied for by the sub-merchant on the WeChat Official Accounts Platform. WeChat Pay will configure the binding relationship when the sub-merchant applies for merchant features. Note:Only for Institutional mode Example: wx8888888888888888
Institution's Merchant ID
sp_mchid
strin[1,32]
Yes
Institution's Merchant ID assigned by WeChat Pay Note:Only for Institutional mode Example: 1900000109
Sub-merchant ID
sub_mchid
string[1,32]
Yes
Sub-merchant ID assigned by WeChat Pay Note:Only for Institutional mode Example: 1900000109
Merchant order No.
out_trade_no
string[1,32]
Yes
Returned merchant's order No. Example: 1217752501201407033233368018
Transaction type
trade_type
string[1,16]
Yes
Transaction type MICROPAY: Quick Pay Example ：MICROPAY
Transaction status
trade_state
string[1,32]
Yes
SUCCESS：Payment successful REFUND：Transferred to refund NOTPAY：Unpaid CLOSED：Closed REVOKED：Revoked (Quick Pay) USERPAYING：Payment in progress PAYERROR：Payment failed (other reasons, for example, failed to be returned by the bank) Example: SUCCESS
Transaction status description
trade_state_d esc
string[1,256]
Yes
Descriptions on the current order status and instructions for the next operation. Example: Payment failed. Place another order and pay it again.
Paying bank
bank_type
string[1,32]
Yes
Bank type, which is the bank ID in string format. See Bank Type for the list of values. Example: CMC
Merchant data
attach
string[1,127]
No
Additional data, which will be returned unchanged in the query API and payment notifications. This field is mainly used for the custom data in the orders of the merchant. Example: Custom data
Payment completion time
success_time
string[1,64]
Yes
Order payment completion time, in RFC3339 format. For example, 2018-06-08T10:34:56+08:00 represents BJT 10:34:56 June 8, 2018. Example: 2018-06-08T10:34:56+08:00
Payer
payer
object
Yes
Body Payer information. For more information, see the description below.
Payer
Name
Variable Name
Type
Required
Description
User ID
openid
string[1,128]
No
The unique user ID corresponding to the merchant's appid. It is returned only when appid is passed.
Note: Only for Common mode Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
Institution user ID
sp_openid
string[1,128]
No
The unique user ID corresponding to the merchant's sp_appid. It is returned only when sp_appid is passed.
Note: Only for Institutional mode Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
Sub-merchant user ID
sub_openid
string[1,128]
No
The unique user ID corresponding to the merchant's sub_appid. It is returned only when sub_appid is passed.
Note: Only for Institutional mode Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
Order amount
amount
object
Yes
Information on the order amount. For more information, see the description below. Example: 1900000109
Discount feature
promotion_detail
array
No
Discount feature info. For more information, see the description below.
Discount feature
Name
Variable Name
Type
Required
Description
Voucher ID
promotion_id
string[1,32]
Yes
Voucher or discount ID
Example: 109519
Discount name
name
string[1,64]
No
Discount name
Example: Single-item discount-6
Discount range
scope
string[1,32]
No
GLOBAL : All-item voucher SINGLE : Single-item discount
Example: SINGLE
Discount type
type
string[1,32]
No
COUPON : Vouchers, which are a kind of top-up vouchers that require fund settlement (the voucher currency of overseas merchants is the same as the payment currency). DISCOUNT: Discount vouchers, which are a kind of top-up-free discount vouchers that require no fund settlement (the voucher currency of overseas merchants is the same as the priced currency).
Example: DISCOUNT
Discount voucher price
amount
int
Yes
The discount amount
Example: 5
Currency type
currency
string[1,16]
No
Three-letter code in accordance with ISO 4217.
Example: CNY
Activity ID
activity_id
string[1,32]
No
Batch ID set up by the backend of the WeChat merchant
Example: 931386
Contribution by WeChat
wechatpay_contribute_amount
int
No
It is the discount provided by the WeChat Pay Merchant Platform, and the total contribution is equal to the total amount of this discount.
Example: 0
Contribution by the merchant
merchant_contribute_amount
int
No
It is the discount provided by the merchant, and the total contribution is equal to the total amount of this discount.
Example: 0
Other contributions
other_contrib ute_amount
int
No
The contributions made by other contributors
Example: 5
Product details
goods_detail
array
No
Product information submitted in JSON format
Product details
Name
Variable Name
Type
Required
Description
Product code
goods_id
string[1,32]
Yes
It consists of a combination of uppercase and lowercase letters, numbers, hyphens and underscores.
Example: Product code
Product remarks
goods_remar k
string[1,128]
No
goods_remark is a remark field that is returned unchanged. It is set when the voucher is configured in the WeChat backend.
Example: 1001
Number of products
quantity
int
Yes
Number of products purchased by a user
Example: 1
Product price
price
int
Yes
Unit: 0.01 CNY. If the merchant provides a discount, the discounted unit price should be transferred (for example, if the user has applied a paper voucher of 50 CNY Off 100 CNY issued by the shop to an order of 100 CNY, the discounted price should be the original price 100 CNY minus 50 CNY).
Example: 528800
Note:
goods_remark is a remark field that is returned unchanged. goods_tag is an order discount tag to distinguish whether an order can be discounted. Both fields are set when the voucher is configured in the WeChat backend.
Response for failed request:
Name
Variable Name
Type
Required
Description
Returned status code
code
string[1,32]
Yes
Error code. See the error code list for the enumerated values.
Returned information
message
string[1,256]
Yes
Returned message. It indicates the reason for the error if not empty.
Detailed error description
detail
object
No
It is returned when code is PARAM_ERROR. Details will be described below.
Detailed error description
Name
Variable Name
Type
Required
Description
The location of incorrect parameter
field
string[1,256]
Yes
If the incorrect parameter is in the JSON for request body, it is populated with the JSON Pointer pointing to this parameter. If the incorrect parameter is in the request URL or querystring, it is populated with the variable name of this parameter.
Value of the incorrect parameter
value
string[1,256]
Yes
Value of the incorrect parameter
Cause of error
issue
string[1,256]
Yes
Cause of error
Location of the incorrect parameter
location
string[1,256]
No
body: The incorrect parameter is in the JSON for request body url: The incorrect parameter is in the request URL query: The incorrect parameter is in the querystring of the request
1{2"code":"INVALID_REQUEST",3"message":"Parameter format verification error",4"promotion_detail'":{5"field":"#/properties/payer",6"value":"1346177081915535577",7"issue":"与ALLOF schema不符",8"location":"body"9}10}
4. Error Codes
Error Message
Description
Solution
INVALID_REQUEST
Invalid request
Check your program based on the error message returned by the API.
TRADE_ERROR
Transaction failed
Prompt the user to change payment method
SYSTEM_ERROR
System error
Call the payment API again with the original request parameters to confirm the result. If SYSTEMERROR is returned again, call the Revoke API and inform the user to change the payment method.
PARAM_ERROR
Incorrect request parameter
Check your program based on the error message returned by the API.
NOT_ENOUGH
Insufficient balance
Prompt the user that the balance is insufficient or to change the payment method
AUTH_CODE_INVALID
Invalid payment code
Check if it is a WeChat payment code. Then initiate the payment again after replacing out_trade_no and the payment code.
