Product Documentation General instructions Access Guidelines FAQs

Identity Information Verification

Update Time：2025.02.20

This API allows merchants to upload the purchaser and payer identity information which will be re-verified by WeChat Pay, and the verification result will be returned for the merchants to correct any wrong information in the declared order

Tips：

WeChat Pay can only push the payer information registered on the system to the customs, regardless of whether the identity information is verified as consistent.
This API can be called only for declared orders.

API intro

Request Url: https://apihk.mch.weixin.qq.com/global/v3/customs/verify-certificate

Request method: POST

API rules：https://wechatpay-api.gitbook.io/wechatpay-api-v3/

Applicable object: Common mode

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.

Request Parameters

Name	Variable Name	Type	Required	Description
Institution APPID	appid	String(32)	Yes	body Specifies Official Account ID assigned by WeChat Example：wxd678efh567hg6787
Merchant ID	mchid	String(32)	Yes	body Specifies Merchant ID assigned by WeChat Payment Example：1230000109
Merchant order No.	out_trade_no	String(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(32)	Yes	body Order No. returned by WeChat Pay Example：1000320306201511078440737890
Customs	customs	String(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(32)	Yes	body Customs registration No. of the merchant Example：123456
Merchant sub-order No.	sub_order_no	String(32)	No	body Merchant sub-order No. It is required if there is a split order. Example：20150806125346
ID type	certificate_type	String(16)	Yes	body Upload fixed value IDCARD. Currently only Mainland China ID cards are supported. Example：IDCARD
ID No.	certificate_id	String	Yes	body Mainland China ID card number. If the last digit is letter X, capitalize the letter X. This field needs to be encrypted. Example：330821198809085211
Name on ID card	certificate_name	String	Yes	body Name on ID card, which needs to be encrypted. Example：Zhang San

Example：

1
2{
3  "appid": "wxd678efh567hg6787",
4  "mchid": "1230000109",
5  "out_trade_no": "20150806125346",
6  "transaction_id": "1000320306201511078440737890",
7  "sub_order_no": "20150806125346",
8  "customs": "SHANGHAI_ZS",
9  "merchant_customs_no": "123456",
10  "certificate_type": "IDCARD",
11  "certificate_id": "330821198809085211",
12  "certificate_name": "Zhang San"
13}

To encrypt fields, refer to the following encryption algorithm:

1、Obtain the WeChat Pay Platform certificate and corresponding platform certificate serial number. The serial number is required to be passed for "Wechatpay-Serial" of the HTTP header of this API request.

2、Perform the RSA encryption for the parameter values with the public key of the WeChat Pay Platform certificate. Use `RSAES-PKCS1-v1_5` as the filling scheme.

3、The encrypted ciphertext that is encoded with base64 is used as the value of the appropriate parameter in the request.

Return Data

Normal return

Name	Variable Name	Type	Required	Description
Institution APPID	appid	string(32)	Yes	Official Account ID assigned by WeChat Example：wxd678efh567hg6787
Merchant ID	mchid	string(32)	Yes	Merchant ID assigned by WeChat Pay Example：1230000109
Merchant order No.	out_trade_no	string(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(32)	Yes	Order No. returned by WeChat Pay Example：1000320306201511078440737890
Identity verification result	Verify_department_trade_id	string(32)	Yes	Verification result of the purchaser and payer identity information SAME - Identity information is matched. DIFFERENT - Identity information is not matched. Example：UNCHECKED

Abnormal return

Name

Variable Name

Type

Required

Description

Return Status Code

return_code

String(32)

Yes

Error code. See the error code list for the enumerated values.
Example：INVALID_REQUEST

Returned message

message

String(256)

Yes

Returned message. If not empty, it presents the cause of the error.
Example：Parameter format verification error

Detailed error description

detail

Object

No

It is returned when code is PARAM_ERROR. Details will be described below

Detailed error description

Example：

1{
2  "appid": "wxd678efh567hg6787",
3  "mchid": "1230000109",
4  "out_trade_no": "20150806125346",
5  "transaction_id": "1000320306201511078440737890",
6  "certificate_check_result": "UNCHECKED"
7}

Error Codes

Error Codes	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.
NOAUTH	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.
PARAM_ERROR	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.