Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Quick Pay API

Latest update time:2023.10.19 Release notes

This API can be used to query all WeChat Pay orders. Merchants can use the Query Order API to query the order status and then complete subsequent business logic.

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


Pathparameter is a path parameter.
Queryparameter needs to be passed in the request URL.
Bodyparameter 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 forCommon mode
Example: wx8888888888888888
Merchant ID mchid string[1,32] Yes Body Merchant ID assigned by WeChat Pay
Note:Only forCommon 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 forInstitutional 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 forInstitutional mode
Example: wx8888888888888888
Institution's Merchant ID sp_mchid string[1,32] Yes Body Institution's Merchant ID assigned by WeChat Pay
Note:Only forInstitutional mode
Example: 1900000109
Sub-merchant ID sub_mchid string[1,32] Yes Body Sub-merchant ID assigned by WeChat Pay
Note:Only forInstitutional 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.
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.
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.
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.
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.
Name Variable Name Type Required Description
Original order price cost_price int No 1. The payment for a merchant's order may be split, and the original order price indicates the transaction amount of the entire order.
2. If the original order price is different from the payment amount, the discount is not available.
3. 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.
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 Eample:


{
	"sp_appid": "wxdace645e0bc2c424",
	"sp_mchid": "10000100",
	"sub_mchid": "20000100",
	"out_trade_no": "20150806125346",
	"merchant_category_code": "4111",
	"payer": {
		"auth_code": "134650720866361395"
	},
	"trade_type": "MICROPAY",
	"amount": {
		"total": 1,
		"currency": "HKD"
	},
	"attach": "Payment Test",
	"description": "Image Store - Tencent Building in Shenzhen - QQ Doll",
	"goods_tag": "1234",
	"limit_pay": "no_credit",
	"detail": [{
				"cost_price": 1,
				"receipt_id": "1234",
				"goods_detail": [{
					"goods_id": "iphone6s_16G",
					"wxpay_goods_id": "3405",
					"goods_name": "iPhone6s 16G",
					"quantity": 1,
					"price": 1
				}]
			}],
				"scene_info": {
					"payer_client_ip": "14.23.150.211",
					"device_ip": "59.37.125.32",
					"device_id": "013467007045764",
					"operator_id": "P001",
					"store_info": {
						"id": "SZTX001",
						"name": "Tencent Building Branch",
						"address": "Nanshan District, Shenzhen, Guangdong"
					}
				}
			}
  

{
	"appid": "wxdace645e0bc2c424",
	"mchid": "10000100",
	"out_trade_no": "20150806125346",
	"merchant_category_code": "4111",
	"payer": {
		"auth_code": "134650720866361395"
	},
	"trade_type": "MICROPAY",
	"amount": {
		"total": 1,
		"currency": "HKD"
	},
	"attach": "Payment Test",
	"description": "Image Store - Tencent Building in Shenzhen - QQ Doll",
	"goods_tag": "1234",
	"limit_pay": "no_credit",
	"detail": {
		"cost_price": 1,
		"receipt_id": "1234",
		"goods_detail": [{
			"goods_id": "iphone6s_16G",
			"wxpay_goods_id": "3405",
			"goods_name": "iPhone6s 16G",
			"quantity": 1,
			"price": 1
		}]
	},
	"scene_info": {
		"payer_client_ip": "14.23.150.211",
		"device_ip": "59.37.125.32",
		"device_id": "013467007045764",
		"operator_id": "P001",
		"store_info": {
			"id": "SZTX001",
			"name": "Tencent Building Branch",
			"address": "Nanshan District, Shenzhen, Guangdong"
		}
	}
}

									{
										"stock_id": ".NET",
										"limit": 10,
									}

									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

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 forCommon mode
Example: wx8888888888888888
Merchant ID mchid string[1,32] Yes Merchant ID assigned by WeChat Pay
Note:Only forCommon 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 forInstitutional 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 forInstitutional mode
Example: wx8888888888888888
Institution's Merchant ID sp_mchid strin[1,32] Yes Institution's Merchant ID assigned by WeChat Pay
Note:Only forInstitutional mode
Example: 1900000109
Sub-merchant ID sub_mchid string[1,32] Yes Sub-merchant ID assigned by WeChat Pay
Note:Only forInstitutional 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.
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 forCommon 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 forInstitutional 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 forInstitutional mode
Example: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
Order amount amount object

Yes

Information on the order amount. For more information, see the description below.
Example: 1900000109
Name Variable Name Type Required Description
Order amount total int Yes The total order amount. The minimum unit of the currency can only be an integer. See “Transaction amount” for details.
Example: 888
Currency type currency string[1,16] No Three-letter code in accordance with ISO 4217
Example: CNY
User's payment amount payer_total int Yes The actual amount paid by the user. The minimum unit of the currency can only be an integer. See “Transaction amount” for details.
Example: 888
Payment currency type payer _currency string[1,16] No Three-letter code in accordance with ISO 4217.
Example: CNY
Exchange rate exchange_rate object No Exchange rate information
Name Variable Name Type Required Description

Exchange rate type

type string[1,32] No SETTLEMENT_RATE: which is the exchange rate between the priced currency and the settlement currency.
Example: SETTLEMENT_RATE
Exchange rate value rate int No The rate value is the exchange rate multiplied by the 8th power of 10. If the priced currency is the same as the settlement currency, then the exchange rate is 1, and the exchange rate value is 100,000,000; if the priced currency is different from the settlement currency, for example, the exchange rate between USD and CNY is 6.5, then the exchange rate value is 650,000,000.
Example: 80000000
Discount feature promotion_detail array No Discount feature info. For more information, see the description below.
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
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.
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

Response Example:


{
	"id": "1008450740201411110005820873",
	"sp_appid": "wx2421b1c4370ec43b", 
	"sub_appid": "",
	"sp_mchid": "10000100",
	"sub_mchid": "20000100",
	"out_trade_no": "20150806125346", 
	"payer": {
		"sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0", 
		"sub_openid" : ""
		},
	"amount" : {
		"total": 528800, 
		"currency": "HKD", 
		"payer_total": 518799, 
		"payer_currency": "CNY", 
		"exchange_rate" : {
			"type": "SETTLEMENT_RATE", 
			"rate": 80000000
			}
		},
	"trade_type": "MICROPAY", 
	"trade_status": "SUCCESS", 
	"trade_state_desc": "Payment successful",
	"bank_type": "CCB_DEBIT", 
	"attach": "Payment test",
	"success_time": "2018-06-08T10:34:56+08:00",
	"promotion_detail":
		[{
		"promotion_id":"109519", 
		"name":"Single-item discount-6",
		"scope":"SINGLE",
		"type":"DISCOUNT",
		"amount":1, 
		"currency": "CNY", 
		"activity_id":"931386",
		"wechatpay_contribute_amount":1, 
		"merchant_contribute_amount":0, 
		"other_contribute_amount":0, 
		"goods_detail":
			[{
			"goods_id":"iphone6s_16G", 
			"goods_remark":"Product remarks", 
			"quantity":1,
			"price":528800
			 }]
		}]
}
 
{
	"code": "INVALID_REQUEST",
	"message": "Parameter format verification error",
	"promotion_detail'": {
		"field": "#/properties/payer",
		"value": "1346177081915535577",
		"issue": "与ALLOF schema不符",
		"location": "body"
	}
}

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.



    Page Navigation

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

置顶