Quick Pay

Update Time:2025.01.07

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

Applicable object: Common mode Institutional mode

Request URL: https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/pay

Request method: POST

 

Path parameter is a path parameter.

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

MCC code

merchant_cat egory_code

string[1,16]

Yes

Body Merchant Category Code
Example: 4111

Payer

payer

object

Yes

Body Payer information. For more information, see the description below.

Payer

Order amount

amount

object

Yes

Body Information on the order amount. For more information, see the description below.

Order amount

Scenario information

scene_info

object

No

Body The scenario information object. For more information, see the description below.

Scenario information

Discount feature

detail

array

No

Body Discount feature info. For more information, see the description below.

Discount feature

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": 1
28				}]
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": 1
27		}]
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

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

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

Response Example:

SUCCESS

1{
2	"id": "1008450740201411110005820873",
3	"sp_appid": "wx2421b1c4370ec43b", 
4	"sub_appid": "",
5	"sp_mchid": "10000100",
6	"sub_mchid": "20000100",
7	"out_trade_no": "20150806125346", 
8	"payer": {
9		"sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0", 
10		"sub_openid" : ""
11		},
12	"amount" : {
13		"total": 528800, 
14		"currency": "HKD", 
15		"payer_total": 518799, 
16		"payer_currency": "CNY", 
17		"exchange_rate" : {
18			"type": "SETTLEMENT_RATE", 
19			"rate": 80000000
20			}
21		},
22	"trade_type": "MICROPAY", 
23	"trade_status": "SUCCESS", 
24	"trade_state_desc": "Payment successful",
25	"bank_type": "CCB_DEBIT", 
26	"attach": "Payment test",
27	"success_time": "2018-06-08T10:34:56+08:00",
28	"promotion_detail":
29		[{
30		"promotion_id":"109519", 
31		"name":"Single-item discount-6",
32		"scope":"SINGLE",
33		"type":"DISCOUNT",
34		"amount":1, 
35		"currency": "CNY", 
36		"activity_id":"931386",
37		"wechatpay_contribute_amount":1, 
38		"merchant_contribute_amount":0, 
39		"other_contribute_amount":0, 
40		"goods_detail":
41			[{
42			"goods_id":"iphone6s_16G", 
43			"goods_remark":"Product remarks", 
44			"quantity":1,
45			"price":528800
46			 }]
47		}]
48}

ERROR

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.

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.