实名授权（公众号）

更新时间：2024.11.18

微信支付实名验证

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

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

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

1、授权获取code

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

请求方法

1（请求方式：GET）
2https://payapp.weixin.qq.com/appauth/authindex?mch_id=MCHID&appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect

参数说明

变量名	类型	必填	示例值	描述
mch_id	string	是	1230000109	商户号
appid	string	是	wxd678efh567hg6787	应用唯一标识
redirect_uri	string	是		重定向地址，需要urlencode，需在支付安全域下(商户平台上配置“支付授权目录”)。
response_type	string	是	code	固定填code
scope	string	是	pay_realname	应用授权作用域， pay_realname 实名授权 - 授权姓名和身份证信息
state	string	是		随机字符串，回调时将带上该参数
#wechat_redirect	string	是		必须带上 ”#wechat_redirect”

用户同意授权

如果用户同意授权，页面将跳转至 redirect_uri/?code=CODE&state=STATE。

1code说明 ： code作为换取access_token的票据，每次用户授权带上的code将不一样，code只能使用一次，10分钟未被使用自动过期。

注意：

A、第三方需要用户授权时，跳转到微信授权页Url，并且在该Url中带上回调地址REDIRECT_URI。

B、用户点击确认授权后，页面将回包参数传入请求code接口，然后重定向到第三方，并带上code和state。

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=	预授权码
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	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/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<encryted_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==</encryted_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/bash

cert_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/bash

encrypted_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版)开发者社区微信开放平台微信公众平台腾讯客服