Product Capability API Dictionary Interface Rules Access Specification FAQs Terms Update Log

Customs Declaration

Update Time：2025.01.07

This API allows merchants to submit additional order information required by the customs.

Tips：

Here is the customs registration information of Tenpay, which is generally provided by the customs. If not, refer to the table below:

Tenpay's customs registration name: Tenpay Payment Technology Co., Ltd. Tenpay's 10-digit customs registration No.: 4403169D3W

Payment order declaration rules:

If there is no split order, declare with the out_trade_no and transaction_id during payment and the CNY amount corresponding to the original payment order (if there is a partial refund, the refund amount shall be deducted).

For a split order, declare with sub_order_no transmitted by the declaration API, sub-order_id returned by the API, and the order_fee amount transmitted by the declaration API.

Judgment criteria for split order: The order is considered as a split one if the merchant transmits sub_order_no when the payment declaration API is called.

Identity information verification and declaration rules:

WeChat Pay can only push the payer information registered on the system to the customs, regardless of whether the identity information verification is consistent or not.

WeChat Pay will verify the information again when the merchant calls the modification API to upload new user identity information.

Note: Submit your customs information on the following page before requesting the API. All the customs information you need for declaration shall be submitted be true and valid: http://pay.weixin.qq.com/index.php/extend/customs

1. API Intro

Applicable object： Common mode Institutional mode

API rules：https://apihk.mch.weixin.qq.com/v3/global/customs/orders

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
Institution APPID	appid	string[1,32]	Yes	Body Specifies Official Account ID assigned by WeChat Example: wxd678efh567hg6787
Merchant ID	mchid	string[1,32]	Yes	Body Specifies Merchant ID assigned by WeChat Payment Example: 1230000109
Merchant order No.	out_trade_no	string[1,32]	Yes	Body internal order No. of the merchant system. Should be within 32 characters and can only contain numbers, uppercase and lowercase letters, and _-\|*@. It is unique for a merchant ID. Example: 20150806125346
WeChat order No.	transaction_id	string[1,32]	Yes	Body Order No. returned by WeChat Pay Example: 1000320306201511078440737890
Customs	customs	string[1,32]	Yes	Body Customs for declaration. For the enumerated values, refer to Parameter Specifications Example: SHANGHAI_ZS
Merchant's customs registration No.	merchant_customs_no	string[1,32]	Yes	Body Customs registration No. of the merchant Example: 123456
Tariff	duty	int	No	Body Tariff (in 0.01 CNY). It is not required and will not be submitted to the customs. Example: 88
Merchant sub-order No.	sub_order_no	string[1,32]	No	Body Merchant sub-order No. It is required if there is a split order. Example: 20150806125346
Currency type	fee_type	string[1,32]	No	Body The currency used for order payment via WeChat Pay. Only CNY is currently supported. It is required if there is a split order. Example: CNY
Sub-order amount	order_fee	int	No	Body Sub-order amount (in 0.01 CNY). Cannot exceed the original order amount. order\_fee=transport_fee+product_fee (payable amount = logistics fee + product price). It is required if there is a split order Example: 888
Logistics fee	transport_fee	int	No	Body Logistics fee (in 0.01 CNY). It is required if there is a split order. Example: 888
Product price	product_fee	int	No	Body Product price (in 0.01 CNY). It is required if there is a split order. Example: 888

Request Example：

JSON

1{
2  "appid": "wxd678efh567hg6787",
3  "mchid": "1230000109",
4  "out_trade_no": "20150806125346",
5  "transaction_id": "1000320306201511078440737890",
6  "customs": "SHANGHAI_ZS",
7  "merchant_customs_no": "123456",
8  "duty": 888,
9  "sub_order_no": "20150806125346",
10  "fee_type": "CNY",
11  "order_fee": 888,
12  "transport_fee": 888,
13  "product_fee": 888
14}

3. Response Parameters

Response for successful request:

Name	Variable Name	Type	Required	Description
Institution APPID	appid	string[1,32]	Yes	Official Account ID assigned by WeChat Example: wxd678efh567hg6787
Merchant ID	mchid	string[1,32]	Yes	Merchant ID assigned by WeChat Pay Example: 1230000109
Declaration status	state	string[1,32]	Yes	Declaration result status code PROCESSING：Declaration in process UNDECLARED：Undeclared SUBMITTED：Modified but not declared SUCCESS：Declaration succeeded FAIL：Declaration failed EXCEPT：Exceptional customs API Example: PROCESSING
Merchant order No.	out_trade_no	string[1,32]	Yes	internal order No. of the merchant system. Should be within 32 characters and can only contain numbers, uppercase and lowercase letters, and _-\|*@. It is unique for a merchant ID. Example: 20150806125346
WeChat order No.	transaction_id	string[1,32]	Yes	Order No. returned by WeChat Pay Example: 1000320306201511078440737890
Merchant sub-order No.	sub_order_no	string[1,32]	No	Merchant sub-order No., which is returned for a split order. Example: 20150806125346
WeChat sub-order No.	sub_order_id	string[1,32]	No	WeChat sub-order No., which is returned for a split order. Example: 20150806125346
Verification institution	verify_department	string[1,16]	Yes	Verification institution code UNIONPAY：Unionpay NETSUNION：NetsUnion OTHERS：Others Example: UNIONPAY
Transaction ID from verification institution	Verify_department_trade_id	string[1,64]	Yes	Transaction ID from the verification institution (such as UnionPay) for the merchant to register at the customs Example: 2018112288340107038204310100000

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	"appid": "wxd678efh567hg6787",
3	"mchid": "1230000109",
4	"state": "PROCESSING",
5	"out_trade_no": "20150806125346",
6	"transaction_id": "1000320306201511078440737890",
7	"sub_order_no": "20150806125346",
8	"sub_order_id": "20150806125346",
9	"verify_department": "UNIONPAY",
10	"verify_department_trade_id": "2018112288340107038204310100000"
11}

ERROR

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"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	The information re-entered by merchant for customs declaration is different from the original one	To modify payment order information, use the Declaration Modification API; to push a payment order again, use the Information Re-push API.
	Customs information is not configured	The customs declaration API is only accessible after the customs information has been configured for the merchant. Please configure the customs information by referring to the customs registration guidelines above.
	Order amount does not match	The order amount for declaration must be same as the payment amount. Check whether the order amount for declaration is correct.
	Declaration is not allowed for refunded orders.	The merchant has not registered with the current customs. Try again after the registration is completed.
NOAUTH	The merchant has not registered with the current customs	The merchant has not registered with the current customs. Try again after the registration is completed.
NOAUTH	Self-Clearance is not enabled.	Check whether the Self-Clearance tool has been enabled for the merchant ("WeChat Pay Merchants Platform" > "Product Center" > "Apply for Self-Clearance").
PARAM_ERROR	Merchant ID (mch_id) is not set	Merchant ID is required. Check whether the merchant ID is empty.
	Invalid merchant ID length	The Merchant ID here must be 10 digit number.
	Currency is not set	Currency is required for split declaration. Check whether fee_type is empty.
	Merchant order No. (out_trade_no) is not set	Check whether the merchant order No. (out_trade_no) is empty.
	WeChat order No. (transaction_id) is not set.	Check whether the WeChat order No. (transaction_id) is empty.
	Invalid WeChat order No. length	WeChat order No. should be a 28-digit number. Check whether the WeChat order No. (transaction_id) is correct.
	Customs information is not set	Customs information is required. Check whether it is empty.
	Customs registration No. is not set	Check whether the registration No. is empty.
	Invalid customs registration No. length	Customs registration No. should be a 6-digit string. Check whether the registration No. is correct.
	Invalid sub-order No. length (sub_order_no)	Sub-order No. should be a string with a maximum of 32 digits. Check whether the sub-order No. is correct.
	AppId is not set	Check whether appid is correct.
	Transaction currency is different from merchant's settlement currency	Check whether the currency parameter (fee_type) is empty.
	Parameter error	Invalid parameter. The parameter may be incorrect or is missing. Check whether the API parameters have been summited as required.
	Incorrect order amount	The order amount is different from the payment order amount. Make a check and declare again.
	Incorrect transaction order information	The transaction order information is incorrect. Make a check and declare again.
	Merchant's split declaration amount is incorrect.	The merchant's split order amount is greater than the amount of the original payment order. Make a check and declare again.
	Transaction currency is different from merchant's settlement currency.	Declare again, or contact WeChat Pay Assistant to find out the reason.
	Missing parameters in split declaration.	Parameters fee_type, order_fee, transport_fee, and product_fee are required for split order.
SYSTEMERROR	System error	Declare again, or contact WeChat Pay Assistant to find out the reason.