WeChat Pay Open Platform

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

pack up

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

pack up

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

pack up

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

pack up

Request Eample：

Institution Mode Common Mode


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

pack up

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

pack up

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

pack up

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

pack up

Response Example:

SUCCESS ERROR


{
	"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.

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Payments

Funding Products

Other Products

Quick Pay API

1. API intro

2. Request Parameters

Request Eample：

3. Response Parameters

Response for successful request:

Response for failed request:

Response Example:

4. Error Codes