实名验证（小程序）

更新时间：2025.03.21

微信支付实名验证

微信支付实名信息验证接口，提供了验证微信用户的姓名和身份证信息是否匹配的功能。
微信支付商户使用实名信息验证接口前, 需要取得微信用户的授权。
获取微信用户的授权, 需要使用微信支付提供的OAuth2.0服务

接口常见问题：

1、调用实名验证接口返回：网络异常，请重试，是什么原因？

2、调用实名验证授权获取code接口返回：{" retcode" :"参数错误","retmsg" :"商户签名验证失败"}是什么原因？

3、小程序实名验证业务流程图中的“提供访问牌”指的是什么？

关于OAuth2.0的详细介绍，可以参考OAuth2.0协议标准。

使用标准OAuth2.0协议接入微信支付，在用户授权的条件下，将可以做到访问用户资源，使用接口调用用户功能（如获取用户实名信息等）

业务流程：

实名交互：

跳转目标 - 实名授权小程序的appid : wx88736d7d39e2eda6

1、授权获取code

在商户需要访问用户受限资源时，需要得到用户的授权，商户小程序调用本接口打开授权小程序取得用户同意后获取授权码。

请求方法

1授权小程序页面路径：pages/oauth/authindex

参数说明

变量名	类型	必填	示例值	描述
api_version	string	是	1.0	API接口版本号，取固定值 “1.0”
mch_id	string(32)	是	1230000109	微信支付分配的商户号
appid	string(32)	是	wx88736d7d39e2eda6	发起授权小程序的appid
response_type	string(32)	是	code	值只能为“code”
scope	string	是	pay_identity	应用授权作用域， pay_identity 是实名验证 - 校验姓名和身份证是否匹配
openid	string(128)	是	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	此参数为微信用户在商户对应appid下的唯一标识
sign	String(128)	是	029B52F67573D7E3BE74904BF9AEA2F48656AEBCBB93FA48D9B70F98D2E23D09	通过签名算法计算得出的签名值，详见签名生成算法
nonce_str	String(32)	是	ibuaiVcKdpRxkhJA	随机字符串，长度要求在32位以内。推荐随机数生成算法
sign_type	String(128)	是	HMAC-SHA256	签名类型，仅支持HMAC-SHA256

请求包体样例：

1{
2	"api_version" : "1.0",
3	"mch_id" : "1230000109",
4	"appid" : "wx88736d7d39e2eda6",
5	"scope" : "pay_identity",
6	"response_type" : "code",
7	"openid" : "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
8	"sign_type" : "HMAC-SHA256",
9	"sign" : "DBB47C037C812B29E0E7B4C5F62972B92E61CF05DE14FA958D9054B2",
10	"nonce_str" : "190703203728315382"
11  }

返回说明

正确时返回的JSON数据包如下：

成功时返回（auth_code用于换取访问令牌,有效期600秒）

1{
2"auth_code" : "EYJV9lz4yHrepHG5ye8Cp0bMORiob11lGgDUGFi26vEX-sirjL5652SFxs9
3WP-zD6TcrbSArk_laGU6A08pgfHxX_tZWdPiP-Cu2a68d-3Q="
4　}

失败时返回

1　{
2	"err_code" : "SYSTEMERROR",
3	"err_code" : "系统错误"
4　}

参数说明

变量名	类型	必填	示例值	描述
以下字段仅在授权失败时返回
err_code	string(32)	否	SYSTEMERROR	错误码，详见错误码说明
err_code_des	string(256)	否	系统错误	错误信息描述
以下字段仅在授权成功时有返回
auth_code	string	否	XDSFLKKASJBASD81923LKDSFH	用于换取访问令牌,有效期600秒

错误码

错误码	错误说明
PARAM_ERROR	参数错误，例如漏传必填参数、参数值错误等
INVALID_REQUEST	非法请求，例如没有访问权限、appid/mchid无效等
SYSTEM_ERROR	微信支付系统错误

2、通过code 换取accesstoken

获取微信用户的授权, 需要使用微信支付提供的 OAuth2.0 服务.用授权小程序得到的授权码调用OAuth2.0接口access_token.

请求方法

1（请求方式：GET）
2https://api.mch.weixin.qq.com/appauth/getaccesstoken?mch_id=MCHID&appid=APPID&openid=OPENID&code=CODE&scope=SCOPE&grant_type=authorization_code&sign_type= HMAC-SHA256&sign=SIGN

参数说明

变量名	类型	必填	示例值	描述
mch_id	string	是	1230000109	商户号
appid	string	是	wxd678efh567hg6787	应用唯一标识
openid	string	是	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	用户openid
code	string	是	EYJV9lz4yHrepHG5ye8Cp0bMORiob11lGgDUGFi26vEX-sirjL5652SFxs9WP-zD6TcrbSArk_laGU6A08pgfHxX_tZWdPiP-Cu2a68d-3Q=	第一步返回的auth_code
grant_type	string	是	authorization_code	填authorization_code
scope	string	是	pay_identity	应用授权作用域， pay_identity 是实名验证 - 校验姓名和身份证是否匹配
sign_type	string	是	HMAC-SHA256	固定填 HMAC-SHA256
sign	string	是	029B52F67573D7E3BE74904BF9AEA2F48656AEBCBB93FA48D9B70F98D2E23D09	通过签名算法计算得出的签名值，详见签名生成算法

返回说明

正确时返回的JSON数据包如下：

1{
2"retcode":0,
3"retmsg":"ok",
4"access_token":"Ca5sECXTwzkWYXs_do9ZaEeueqVHOtF-nXr51yNll2O97zqk9niwJnmSWxhDJELqoDDVFws6LCBbSulnEAaxCg==",
5"access_token_expire_in":7200,
6"refresh_token":"Q2eOMW_fnMX4U18SAGr2CuONaNgE3qYRP8eJUHKjFjz65ddh7DGb2koRG5ij-rlHohDmyEpz1wKSH9jPiAAJzg==",
7"refresh_token_expire_in":2592000
8}

参数说明

变量名	类型	必填	示例值	描述
retcode	int	是	0	0-成功
retmsg	string	是	OK	处理成功，返回ok 其他情况返回具体错误码
access_token	string	是	Ca5sECXTwzkWYXs_do9ZaEeueqVHOtF-nXr51yNll2O97zqk9niwJnmSWxhDJELqoDDVFws6LCBbSulnEAaxCg==	接口调用凭证
access_token_expire_in	string	是	7200	请求返回的access_token过期时间，以秒为单位，有效期较短
refresh_token	string	是	Q2eOMW_fnMX4U18SAGr2CuONaNgE3qYRP8eJUHKjFjz65ddh7DGb2koRG5ij-rlHohDmyEpz1wKSH9jPiAAJzg==	refresh令牌
refresh_token_expire_in	string	是	2592000	refresh_token过期时间，以秒为单位，有效期较长

3、微信支付实名验证

取得token后调用本接口验证微信用户的姓名和身份证信息是否匹配

请求方法

1（请求方式：POST）
2（请使用https协议）https://fraud.mch.weixin.qq.com/secsvc/realnameauth

参数说明

变量名	类型	必填	示例值	描述
version	String(8)	是	1.0	接口版本号 1.0
mch_id	String(32)	是	1230000109	微信支付商户号
appid	String(32)	是	wxd678efh567hg6787	微信appid
openid	String(128)	是	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	openId
real_name	String(64)	是	刘某某	真实姓名，请使用UTF-8编码
cred_type	int	是	1	证件类型， 1：身份证 2：护照 5：回乡证 9：台胞证 12：外国人居留证 17：港澳居民居住证 18：台湾居民居住证
cred_id	String(32)	是	440000000000000000	证件号码.
nonce_str	String(32)	是	ec2316275641faa3aacf3cc599e8730f	随机字符串. 随机字符串，不长于32位。
access_token	String(128)	是		步骤2或步骤3获取到的access_token
sign	String(128)	是	0CB01533B8C1EF103065174F50BCA001	通过签名算法计算得出的签名值，详见签名生成算法
sign_type	String(32)	是	HMAC-SHA256	签名类型，支持MD5和HMAC-SHA256 签名算法和校验签名的工具参考

请求包体样例：

1<xml>
2   <version >1.0</version>　 
3   <mch_id>xxxx</mch_id>
4   <appid>xxxx</appid>
5   <openid>xxx</openid>
6   <real_name>xxx</real_name> 
7   <cred_id>xxx</cred_id>
8   <cred_type>1</cred_type>
9   <access_token>xxx</access_token>
10   <nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
11   <sign_type>HMAC-SHA256</sign_type>
12   <sign>0CB01533B8C1EF103065174F50BCA001</sign>
13</xml>

返回说明

正确时返回的XML数据包如下：

1<xml>
2   <return_code><![CDATA[SUCCESS]]></return_code>
3   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
4   <mch_id><![CDATA[10000100]]></mch_id>
5   <nonce_str><![CDATA[IITRi8Iabbblz1Jc]]></nonce_str>
6   <openid><![CDATA[oUpF8uMuAJO_M2pxb1Q9zNjWeS6o]]></openid>
7   <sign><![CDATA[7921E432F65EB8ED0CE9755F0E86D72F]]></sign>
8   <result_code><![CDATA[SUCCESS]]></result_code>
9   <verify_openid><![CDATA[V_OP_NM_MA]]></verify_openid>
10   <verify_real_name><![CDATA[V_NM_ID_MA]]></verify_real_name>
11</xml>

参数说明

变量名	类型	必填	示例值	描述
return_code	String(16)	是	SUCCESS	返回状态码 SUCCESS/FAIL. 此字段是通信标识，非交易标识交易是否成功需要查看result_code来判断
return_msg	String(128)	否	OK	返回信息，如非空，为错误原因签名失败, 参数格式校验错误等
以下字段在return_code为SUCCESS的时候有返回
result_code	String(16)	是	SUCCESS	业务结果 SUCCESS/FAIL
err_code	String(32)	否	INVALID_SIGN_TYPE	错误代码
err_code_desc	String(128)	否	签名类型错误	错误代码描述
appid	String(32)	是	wx2421b1c4370ec43b	应用唯一标识
mch_id	String(32)	是	10000100	微信支付商户号
nonce_str	String(32)	是	IITRi8Iabbblz1Jc	随机字符串. 随机字符串，不长于32位。
sign	String(32)	是	7921E432F65EB8ED0CE9755F0E86D72F	通过微信支付签名算法计算得出的签名值。
以下字段在return_code 和result_code都为SUCCESS的时候有返回
openid	String(128)	是	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	OpenId
access_token	String(128)	是		步骤2或步骤3获取到的access_token
verify_openid	String(256)	否	V_OP_NM_MA	有多个结果时用分号”;”连接 V_OP_NA：用户暂未实名认证 V_OP_NM_MA：用户与姓名匹配 V_OP_NM_UM：用户与姓名不匹配
verify_real_name	String(32)	否	V_NM_ID_MA	当verify_openid为V_OP_NM_MA时返回: V_NM_ID_MA：姓名与证件号匹配 V_NM_ID_UM：姓名与证件号不匹配 V_NM_ID_TYPE_UM：证件类型不匹配
bind_bankcard	String(32)	否	YES	当verify_real_name为V_NM_ID_MA时返回： YES: 绑定银行卡的实名认证 NO: 非绑定银行卡的实名认证 ( version 1.1的新增字段， version> = 1.1时返回)

错误码

错误码	错误说明
PARAM_INVALID	参数非法
INVALID_REQUEST	非法请求，例如没有访问权限、appid/mchid无效等
POST_IVALID_XML_DATA	XML格式错误
INVALID_SIGN_TYPE	签名类型错误
SIGN_ERROR	签名错误
LACK_MCH_ID	参数中缺少MCHID
WRONG_MCHID	商户号不存在
ACCESS_TOKEN_EXPIRE	access_token已过期
ACCESS_TOKEN_INVALID	access_token非法
OPENID_INVALID	openid非法
NO_API_AUTH	商户无接口API接口权限
ERR_UNKOWN_VERIFY_STATE	用户的实名状态非法
SYSTEM_ERROR	系统错误
UNKNOWN_ERROR	未知错误

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服