Identity Information Verification

Update Time:2025.01.07

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.


1. API Intro

Applicable object: Common mode Institutional mode

API rules:https://apihk.mch.weixin.qq.com/v3/global/customs/verify-certificate

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

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

ID type

certificate_type

string[1,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

Request Example:

JSON

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

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

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

Identity verification result

Verify_department_trade_id

string[1,32]

Yes

Verification result of the purchaser and payer identity information
SAME - Identity information is matched.
DIFFERENT - Identity information is not matched.
Example: UNCHECKED

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  "out_trade_no": "20150806125346",
5  "transaction_id": "1000320306201511078440737890",
6  "certificate_check_result": "UNCHECKED"
7}

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

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.

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.