Query Customs Declaration
Update Time:2025.01.07Merchants query additional order information submitted and declaration status by order No.
1. API Intro
Applicable object: Common mode Institutional mode
API rules:https://apihk.mch.weixin.qq.com/v3/global/customs/orders
Request method:GET
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 | Query Specifies Official Account ID assigned |
Merchant ID | mchid | string[1,32] | Yes | Query pecifies Merchant ID assigned by |
Order type | order_type | string[1,16] | Yes | Query Select one of the four order types: out_trade_no - Merchant order No. |
Order No. | order_no | string[1,32] | Yes | Query Specify an order No. depending on the selected order type. |
Customs | customs | string[1,32] | Yes | Query Customs for declaration. For the enumerated values, refer to Parameter Specifications |
Offset | offset | int | No | Query CA non-negative integer, which indicates the start position of requested resources, starting from 0. Optional. It is 0 by default. |
Maximum number of returned records | limit | int | No | Query A positive integer, which indicates the maximum number of resource records that can be returned for this request. Optional. The suggested default value is 20. |
Request Example:
URL
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 | |||
Merchant ID | mchid | string[1,32] | Yes | Merchant ID assigned by WeChat Pay | |||
WeChat order No. | transaction_id | string[1,32] | Yes | Order No. returned by WeChat Pay | |||
Verification institution | verify_department | string[1,16] | Yes | Verification institution code | |||
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 | |||
Offset | offset | int | Yes | The offset from which the resource records are returned for the request | |||
Maximum number of returned records | limit | int | Yes | The maximum number of returned records for the request | |||
Total number of query results | total_count | int | Yes | Total number of query results | |||
Customs declaration data packet | data | Array | Yes | Total number of query results | |||
|
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. | |||
|
Response Example:
SUCCESS
ERROR
4. Error Codes
Error Message | Description | Solution |
---|---|---|
INVALID_REQUEST | Payer's ID No. registered in WeChat is invalid. Please make a check. | There is a problem with the payer's identity information registered in WeChat. Contact WeChat Pay Assistant to find out the reason. |
Customs declaration record does not exist. | The customs declaration record does not exist. Please apply again or contact WeChat Pay Assistant to find out the reason. | |
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. | |
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. |
Self-Clearance is not enabled. error | Check whether the Self-Clearance tool has been enabled for the merchant ("WeChat Pay Merchants Platform" > "Product Center" > "Apply for Self-Clearance"). | |
PARAM_ERROR | Parameter error | Invalid parameter. The parameter may be incorrect or is missing. Check whether the API parameters have been summited as required. |
Merchant entered invalid user ID No. | Enter the correct ID No. If you still get an error, contact WeChat Pay Assistant to find out the reason. | |
SYSTEMERROR | System error | Declare again, or contact WeChat Pay Assistant to find out the reason. |
USER_ACCOUNT_ABNORMAL | The identity information on the payment order for declaration does not match the payer's registered identity information. Customs declaration is not allowed. | The identity information on the payment order for declaration does not match the payer's registered identity information. Enter the actual payer's identity information and declare again. |