实名授权（小程序）

更新时间：2026.08.13

提示：本功能目前处于灰度测试阶段、暂未开放使用，待全量开放后将通过文档门户公告同步，感谢您的理解。

微信支付实名验证

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

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

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

业务流程：

实名交互：

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

1、预下单

在引导用户进入授权流程之前，商户后台调用本接口换取预下单标识 preorder_id，并把它下发给自己的小程序。本接口使用商户API证书（RSA）签名，商户密钥不再需要下发到小程序侧。

请求方法

1（请求方式：POST）
2（请使用https协议）https://api.mch.weixin.qq.com/appauth/wxauthpreorder
3Content-Type: application/json

请求头说明

头部	必填	示例值	描述
Authorization	是	WECHATPAY2-SHA256-RSA2048 mchid="1230000109",...	V3认证信息，格式见下方签名说明
Wechatpay-Serial	是	59303040AA42CB61E0C059E8E6156C9F0F2A1E5E	微信支付平台证书序列号
Content-Type	是	application/json	固定填application/json

参数说明

变量名	类型	必填	示例值	描述
api_version	string	是	3.0	API接口版本号，取固定值 “3.0”
mch_id	string(32)	是	1230000109	微信支付分配的商户号，必须与Authorization头中的mchid一致
appid	string(32)	是	wx88736d7d39e2eda6	发起授权小程序的appid
scope	string	是	pay_realname	应用授权作用域， pay_realname: 实名授权 - 授权姓名和身份证信息
response_type	string(32)	是	code	值只能为“code”
openid	string(128)	是	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	此参数为微信用户在商户对应appid下的唯一标识
credential_type	String(32)	否	MAINLAND_ID	获取证件类型，空表示不限制,当前仅支持：MAINLAND_ID 此处填写的值在第二步必须原样传回
nonce_str	String(32)	否	ibuaiVcKdpRxkhJA	随机字符串，长度要求在32位以内。推荐随机数生成算法

请求包体样例：

1{
2  "api_version" : "3.0",
3  "mch_id" : "1230000109",
4  "appid" : "wx88736d7d39e2eda6",
5  "scope" : "pay_realname",
6  "response_type" : "code",
7  "openid" : "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
8  "credential_type" : "MAINLAND_ID",
9  "nonce_str" : "190703203728315382"
10  }

签名说明

Authorization头的格式如下（mchid也可写作mch_id）：

1Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1230000109",nonce_str="593BEC0C930BF1AFEB40B4A08C8FB242",signature="jnks4dlrPw3ZX+ozVvSK39oa...==",timestamp="1554208460",serial_no="408B07E79B8269FEC3D5D3E6AB8ED163A6A380DB"

签名源串由五行组成，每行末尾都有一个换行符，最后一行也不能省略：

1{HTTP请求方法}\n
2{URL，有query时写成 /path?query}\n
3{时间戳}\n
4{随机串}\n
5{请求报文主体}\n

其中时间戳和随机串必须与Authorization头里的timestamp、nonce_str完全一致。用商户API私钥对源串做SHA256-RSA签名后再base64编码，填入signature。

签名示例：

1#!/bin/bash
2private_key_file="./1900006511_rsa_private_key.pem"
3serial_no="408B07E79B8269FEC3D5D3E6AB8ED163A6A380DB"
4mchid="1230000109"
5timestamp=`date +%s`
6nonce=`openssl rand -hex 16 | tr 'a-z' 'A-Z'`
7body='{"api_version":"3.0","mch_id":"1230000109","appid":"wx88736d7d39e2eda6","scope":"pay_realname","response_type":"code","openid":"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o","credential_type":"MAINLAND_ID","nonce_str":"190703203728315382"}'
8
9sign_src="POST
10/appauth/wxauthpreorder
11${timestamp}
12${nonce}
13${body}
14"
15signature=`printf '%s' "$sign_src" | openssl dgst -sha256 -binary -sign $private_key_file | base64 -w 0`
16echo "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"${mchid}\",nonce_str=\"${nonce}\",signature=\"${signature}\",timestamp=\"${timestamp}\",serial_no=\"${serial_no}\""

商户号、证书序列号和私钥文件需要到商户平台上申请。

返回说明

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

1{
2  "preorder_id" : "9F2C1A7E5B3D48A0C6E1F70B2D4A8C35"
3}

失败时返回

1{
2  "code" : "PARAM_ERROR",
3  "err_msg" : "参数错误"
4}

参数说明

以下字段仅在预下单成功时有返回

变量名	类型	必填	示例值	描述
preorder_id	string(32)	否	9F2C1A7E5B3D48A0C6E1F70B2D4A8C35	预下单标识，有效期600秒，有效期内可重复使用

以下字段仅在预下单失败时返回

变量名	类型	必填	示例值	描述
code	string(32)	否	PARAM_ERROR	错误码，详见错误码说明
err_msg	string(256)	否	参数错误	错误信息描述

应答同时返回下列签名头，商户应当用微信支付平台证书验签后再采信应答内容：

响应头	描述
Wechatpay-Signature	应答签名
Wechatpay-Timestamp	应答时间戳
Wechatpay-Nonce	应答随机串
Wechatpay-Serial	微信支付平台证书序列号
Wechatpay-Signature-Type	签名类型

错误码

错误码	错误说明
PARAM_ERROR	参数错误，例如漏传必填参数、参数值错误、mch_id与Authorization头不一致等
SIGN_ERROR	签名错误，请检查签名源串的换行、证书序列号、系统时间偏差
INVALID_REQUEST	非法请求，例如没有访问权限、appid/mchid无效、appid与商户号未绑定等
SYSTEM_ERROR	微信支付系统错误，请用相同参数重试

2、授权获取code

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

请求方法

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

参数说明

变量名	类型	必填	示例值	描述
api_version	string	是	3.0	API接口版本号，取固定值 “3.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下的唯一标识
credential_type	string(32)	否	MAINLAND_ID	获取证件类型，空表示不限制,当前仅支持：MAINLAND_ID 必须与预下单时一致
preorder_id	string(32)	是	9F2C1A7E5B3D48A0C6E1F70B2D4A8C35	第一步预下单返回的预下单标识，有效期600秒

请求包体样例：

1{
2	"api_version" : "3.0",
3	"mch_id" : "1230000109",
4	"appid" : "wx88736d7d39e2eda6",
5	"scope" : "pay_realname",
6	"response_type" : "code",
7	"openid" : "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
8	"credential_type" : "MAINLAND_ID",
9	"preorder_id" : "9F2C1A7E5B3D48A0C6E1F70B2D4A8C35"
10  }

mch_id、appid、scope、openid、credential_type 会与预下单时提交的值逐字段比对，任一不一致或 preorder_id 已过期都会导致授权失败。请直接沿用预下单时使用的值，不要在小程序侧重新拼装。

返回说明

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

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

1{
2  "auth_code" : "EYJV9lz4yHrepHG5ye8Cp0bMORiob11lGgDUGFi26vEX-sirjL5652SFxs9WP-zD6TcrbSArk_laGU6A08pgfHxX_tZWdPiP-Cu2a68d-3Q="
3}

失败时返回

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	微信支付系统错误

3、通过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过期时间，以秒为单位，有效期较长

4、微信支付实名授权

取得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==	步骤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}&timestamp={timestamp}

签名示例：
#!/bin/bashcert_serialno='59303040AA42CB61E0C059E8E6156C9F0F2A1E5E'timestamp=`date +%s`private_key_file="./1900006511_rsa_private_key.pem"ori_content="cert_serialno=${cert_serialno}&timestamp=${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

文档是否有帮助

LLM请查看llms.txt

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