实名授权（小程序）

更新时间：2025.03.21

微信支付实名验证

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

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

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

业务流程：

实名交互：

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

1、授权获取code

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

请求方法

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

参数说明

变量名	类型	必填	示例值	描述
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_realname	应用授权作用域， pay_realname: 实名授权 - 授权姓名和身份证信息
openid	string(128)	是	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	此参数为微信用户在商户对应appid下的唯一标识
sign	String(128)	是	029B52F67573D7E3BE74904BF9AEA2F48656AEBCBB93FA48D9B70F98D2E23D09	通过签名算法计算得出的签名值，详见签名生成算法
nonce_str	String(32)	是	ibuaiVcKdpRxkhJA	随机字符串，长度要求在32位以内。推荐随机数生成算法
credential_type	String(32)	否	MAINLAND_ID	获取证件类型，空表示不限制,当前仅支持：MAINLAND_ID
sign_type	String(128)	是	HMAC-SHA256	签名类型，仅支持HMAC-SHA256

请求包体样例：

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

返回说明

正确时返回的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_realname	应用授权作用域， pay_realname 是实名验证 - 校验姓名和身份证是否匹配
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	uint	是	7200	请求返回的access_token过期时间，以秒为单位，有效期较短
refresh_token	string	是	Q2eOMW_fnMX4U18SAGr2CuONaNgE3qYRP8eJUHKjFjz65ddh7DGb2koRG5ij-rlHohDmyEpz1wKSH9jPiAAJzg==	refresh令牌
refresh_token_expire_in	uint	是	`2592000`	refresh_token过期时间，以秒为单位，有效期较长

3、微信支付实名授权

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

请求方法

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

参数说明

变量名	类型	必填	示例值	描述
version	String(8)	是	1.0	接口版本号 1.0
mch_id	String(32)	是	1230000109	微信支付商户号
appid	String(32)	是	wxd678efh567hg6787	微信appid
openid	String(32)	是	owanlsu9c9KfL1_BMG6cGBqevXw4	openId
cert_serialno	String(64)	是	59303040AA42CB61E0C059E8E6156C9F0F2A1E5E	加密实名信息的证书序列号
access_token	String(128)	是	LGEe-hgvFntzPdePKinbQjHQwJ087FZTZWiDBVbasFmJYfEqLjXTYHMWgAoP2MuRThxRSlqvs2Mi9i2VRCr_MQ==	步骤2或步骤3获取到的access_token
timestamp	uint32	是		unix时间戳，必须获取当前时间。
cert_sign	String(512)	是		使用rsa私钥对证书序列号和unix时间戳的进行签名详见下方签名及数据解密说明
charset	String(5)	否	UTF-8	字符集，固定为UTF-8，不填则表示为GBK
nonce_str	String(32)	是	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	随机字符串. 随机字符串，不长于32位。
sign	String(128)	是	3EB660E79F510A4C35A9527EA73B326A77EC996626BDD80D4F6F07829503455D	通过签名算法计算得出的签名值，详见签名生成算法
sign_type	String(32)	是	HMAC-SHA256	签名类型，支持HMAC-SHA256 签名算法和校验签名的工具参考

请求包体样例：

1<xml>
2   <mch_id>1230000109</mch_id>
3   <appid>wxd678efh567hg6787</appid>
4   <openid>owanlsu9c9KfL1_BMG6cGBqevXw4</openid>
5   <cert_serialno>59303040AA42CB61E0C059E8E6156C9F0F2A1E5E</cert_serialno>      
6   <access_token>LGEe-hgvFntzPdePKinbQjHQwJ087FZTZWiDBVbasFmJYfEqLjXTYHMWgAoP2MuRThxRSlqvs2Mi9i2VRCr_MQ==</access_token>
7   <timestamp></timestamp>
8   <cert_sign></cert_sign>
9   <nonce_str>5K8264ILTKCH16CQ2502SI8ZNMTM67VS</nonce_str>
10   <sign_type>HMAC-SHA256</sign_type>
11   <sign>3EB660E79F510A4C35A9527EA73B326A77EC996626BDD80D4F6F07829503455D</sign>
12</xml>

返回说明

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

1<xml>
2<return_code>SUCCESS</return_code>
3<return_msg>OK</return_msg>
4<appid>wxd678efh567hg6787</appid>
5<mch_id>1230000109</mch_id>
6<nonce_str>IITRi8Iabbblz1Jc</nonce_str>
7<sign>3EB660E79F510A4C35A9527EA73B326A77EC996626BDD80D4F6F07829503455D</sign>
8<result_code>SUCCESS</result_code>
9<encrypted_real_name>Pv1JJAuBLD6IB2cScTCE5XSoBnw6BdoyacMPxcf0Q9ARIXsQab1gy3HMATwd0NlAoMQuCjZYwVoriA/
108oawVuFiUkdAT+l7WC3Ju7WSgFsL1/LQEfFX05mYzJ+wDO0Zwcgntzf2gH7t0F8RL9OPxiejQ0VxYE6YEXBPbvDMW2ZlmIUbNcY
11JTrm3e26ge6mR3u1Gzd/keSPKW8peNM/bIb+ylOOm6jN+0Uu9WWjuk4y5vFZfA1T3/Ts0mKJFCuS+Vcb3zqo5808sGRIfwhGy/
12bbAhH4BwZkCqShNnj+vfCo2WmV4GE1kIgiFDFDaiw3xgkWytvAHJdba+xmuVViMrfQ==</encryted_real_name>
13<encryted_credential_id>hqf+zbbQ899vkwk7ZMWbaiyoUNroriJvduYHc5+/jVhLYLdpwkRpLcxqFebxfYuQYKLVi9TMpR
14cfjrATX5ApKCRU91WRueNj3E1i+L0aYoA+zF0zDv0/RD0Nn+fPsT9WGvc8M4xpmjwPyE2z6boysqGy55gfvJcmDa3snmyDBxZz
15S/Pw1SkK+qScleoYJExmn7KkP5mzD7uNNqi3vPnf4VmxqjpW7GmssTy1LyLSLKjW1ZCcJHieZBrR7O8A6/QSYp6+bZymxYEd7M
16JxQiBt6PocsDdg7uYtUmz7jzITzlLLR0FDZgxotC4j4GYKOOq+50ZgsG2GJ4tN8U7zimARg==</encrypted_credential_id>
17</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)	否	NO_API_AUTH	错误代码
err_code_desc	String(128)	否	商户无此接口权限	错误代码描述
appid	String(32)	是	wxd678efh567hg6787	应用唯一标识
mch_id	String(32)	是	1230000109	微信支付商户号
nonce_str	String(32)	是	IITRi8Iabbblz1Jc	随机字符串. 随机字符串，不长于32位。
sign	String(32)	是	3EB660E79F510A4C35A9527EA73B326A77EC996626BDD80D4F6F07829503455D	通过微信支付签名算法计算得出的签名值。
以下字段在return_code 和result_code都为SUCCESS的时候有返回
encrypted_real_name	String(344)	是		加密后的姓名。如果请求参数charset=UTF-8，解密之后数据为UTF-8格式，否则解密之后数据为GBK格式。
encrypted_credential_id	String(344)	是		加密后的证件号码
cre_type	String(32)	否		证件类型，version >= 2.0时返回此字段证件类型枚举值： MAINLAND_ID：身份证 PASSPOT：护照 MO：军官证 SOLDIERS：士兵证 HVPS：回乡证 MAINLAND_TMP_ID：临时身份证 ACCOUNT_THIN：户口簿 POLICE：警官证 MTPS：台胞证 BL：营业执照 OTHER：其它证件 RPFF：外国人居留证 HK_MACAO：港澳居民居住证 TAIWAN：台湾居民居住证

签名及数据解密说明

由于实名信息属于敏感数据，不能以明文数据传输，所以开发者需要用私钥对请求进行签名(sha256后base64编码).
微信支付会对用户的姓名和身份证信息用开发者的公钥加密 , 加密的padding算法为RSA_PKCS1_PADDING, 开发者可以使用私钥解密出明文
商户号、证书序列号和私钥文件需要到商户平台上申请

签名示例

签名源串: cert_serialno={cert_serialno}×tamp={timestamp}

签名示例：
#!/bin/bashcert_serialno='59303040AA42CB61E0C059E8E6156C9F0F2A1E5E'timestamp=`date +%s`private_key_file="./1900006511_rsa_private_key.pem"ori_content="cert_serialno=${cert_serialno}×tamp=${timestamp}"echo $ori_contentsign=`echo -n $ori_content | openssl dgst -sha256 -binary -sign $private_key_file | base64 -w 0`echo "sign: $sign"

解密示例：

#!/bin/bashencrypted_real_name="BtqSM3KOyt+mDhJhyLCS9vsEoo3gTBupZHwS3i8daCyrUGxlEv+k7cE6U+9eiTo2DPNMouZnPSqv5vRERvwvm//JwkKdrV/xvSB4Ak7mJB+/t4Y4lV6gfeyggzN4xtdWoJfkgm0wa4V7oZGrpnexdwYuwyJYTMoz+87qJRwUfWAgF7U7trJ+b5DvCk9Y6KwT0N4j6PtDAk23k0zg06rTANzU3Mq1IWF7LVBcvSvR9nkNAPzcv06LQ70kxqQqVj5z+H+ERuILwBjuIQozCh6pO37Q3slz8UNnl7r48vw7uZe6be1fSDyf0hYE43n2DMpljnATQOMeJxp7nBrsvwDdPQ=="private_key_file="./1900006511_rsa_private_key.pem"
echo -n $encrypted_real_name | base64 -d | openssl rsautl -decrypt -ssl -inkey $private_key_file | iconv -f gbk -t utf-8

错误码

错误码	错误说明	原因	解决方法
NO_API_AUTH	商户无此接口权限	商户未开通此接口权限	请商户前往申请此接口权限
SYSTEMERROR	系统错误	系统超时	系统异常，请用相同参数重新调用
APPID_NOT_EXIST	APPID不存在	参数中缺少APPID或者非法	请检查APPID是否正确
MCHID_NOT_EXIST	MCHID不存在	参数中缺少MCHID或者非法	请检查MCHID是否正确
APPID_MCHID_NOT_MATCH	appid和mch_id不匹配	appid和mch_id不匹配	请确认appid和mch_id是否匹配
LACK_PARAMS	缺少参数	缺少必要的请求参数	请检查参数是否齐全
SIGNERROR	签名错误	参数签名结果不正确	请检查签名参数和方法是否都符合签名算法要求
XML_FORMAT_ERROR	XML格式错误	XML格式错误	请检查XML参数格式是否正确
REQUIRE_POST_METHOD	请使用post方法	未使用post传递参数	请检查请求参数是否通过post方法提交
POST_DATA_EMPTY	post数据为空	post数据不能为空	请检查post数据是否为空
USER_OPENID_NOT_MATCH	openid和appid不匹配	openid和appid不匹配	请检查openid是否使用当前的appid获取到的
POST_DATA_INVALID	post数据非法	可能包含有敏感词,或者带有XSS攻击之类的，或者请求参数不在接口列表中	请检查参数内容是否合法
INVALID_PARAMS	入参错误	某些入参没有按照约定传入，或者两次传入的不一致	修改有问题的参数再尝试
ACCESS_TOKEN_EXPIRE	access_token已过期	access_token的有效期为2小时	用户重新授权或者商户使用https://api.mch.weixin.qq.com/appauth/refreshtoken获取新的access_token
ACCESS_TOKEN_INVALID	access_token非法	access_token失效, 每个用户在同一个appid下最多只有一个生效的access_token, 用户重复授权后, 会导致老的access_token失效	商户排查是否没有使用最新的access_token,是否使用了其它APPID获取到的access_token

文档是否有帮助

更多支持

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