实名验证(小程序)
微信支付实名验证
关于OAuth2.0的详细介绍,可以参考OAuth2.0协议标准。
使用标准OAuth2.0协议接入微信支付,在用户授权的条件下,将可以做到访问用户资源,使用接口调用用户功能(如获取用户实名信息等)
业务流程:
实名交互:
![]() |
![]() |
跳转目标 - 实名授权小程序的appid : wx88736d7d39e2eda6
1、授权获取code
在商户需要访问用户受限资源时,需要得到用户的授权,商户小程序调用本接口打开授权小程序取得用户同意后获取授权码。
请求方法
授权小程序页面路径: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 |
请求包体样例:
{
"api_version" : "1.0",
"mch_id" : "1230000109",
"appid" : "wx88736d7d39e2eda6",
"scope" : "pay_identity",
"response_type" : "code",
"openid" : "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
"sign_type" : "HMAC-SHA256",
"sign" : "DBB47C037C812B29E0E7B4C5F62972B92E61CF05DE14FA958D9054B2",
"nonce_str" : "190703203728315382",
}
返回说明
正确时返回的JSON数据包如下:
成功时返回(auth_code用于换取访问令牌,有效期600秒)
{
"auth_code" : "EYJV9lz4yHrepHG5ye8Cp0bMORiob11lGgDUGFi26vEX-sirjL5652SFxs9
WP-zD6TcrbSArk_laGU6A08pgfHxX_tZWdPiP-Cu2a68d-3Q="
}
失败时返回
{
"err_code" : "SYSTEMERROR",
"err_code" : "系统错误"
}
参数说明
变量名 | 类型 | 必填 | 示例值 | 描述 | ||
---|---|---|---|---|---|---|
以下字段仅在授权失败时返回 |
||||||
err_code | stirng(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.
请求方法
(请求方式:GET)
https://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数据包如下:
{
"retcode":0,
"retmsg":"ok",
"access_token":"Ca5sECXTwzkWYXs_do9ZaEeueqVHOtF-nXr51yNll2O97zqk9niwJnmSWxhDJELqoDDVFws6LCBbSulnEAaxCg==",
"access_token_expire_in":7200,
"refresh_token":"Q2eOMW_fnMX4U18SAGr2CuONaNgE3qYRP8eJUHKjFjz65ddh7DGb2koRG5ij-rlHohDmyEpz1wKSH9jPiAAJzg==",
"refresh_token_expire_in":2592000
}
参数说明
变量名 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
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 |
是 |
|
refresh_token过期时间,以秒为单位,有效期较长 |
3、微信支付实名验证
取得token后调用本接口验证微信用户的姓名和身份证信息是否匹配
请求方法
(请求方式:POST)
(请使用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 签名算法和校验签名的工具参考 |
请求包体样例:
<xml>
<version >1.0</ version >
<mch_id>xxxx</mch_id>
<appid>xxxx</appid>
<openid>xxx</openid>
<real_name>xxx</real_name>
<cred_id>xxx</cred_id>
<cred_type>1</cred_type>
<access_token>xxx</access_token>
<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
<sign_type>HMAC-SHA256</sign_type>
<sign>0CB01533B8C1EF103065174F50BCA001</sign>
</xml>
返回说明
正确时返回的XML数据包如下:
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<nonce_str><![CDATA[IITRi8Iabbblz1Jc]]></nonce_str>
<openid><![CDATA[oUpF8uMuAJO_M2pxb1Q9zNjWeS6o]]></openid>
<sign><![CDATA[7921E432F65EB8ED0CE9755F0E86D72F]]></sign>
<result_code><![CDATA[SUCCESS]]></result_code>
<verify_openid><![CDATA[V_OP_NM_MA]]></verify_openid>
<verify_real_name><![CDATA[V_NM_ID_MA]]></verify_real_name>
</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 |
未知错误 |