一、能力背景
互联网+国家战略发布以来，各行业紧锣密鼓推进改革。其中，众多政府民生服务，例如社保查询、公积金查询提取、医疗机构挂号、公用事业缴费等均需要用户提供实名信息。此外，手机卡实名办理、火车客运实名购票、酒店实名入住等行业实名制都在推行。
基于此，为了让用户有更好的体验，让各行业的互联网+服务更顺畅，基于微信支付实名用户基础，提供微信支付实名支付账户信息授权接口。即经过用户的授权，小程序的服务提供者可以获得用户在微信支付认证的姓名以及身份证信息。
二、接入必读
名称: getRealnameAuthInfo
功能：经过用户授权，可获得用户在微信支付认证的姓名以及身份证信息（非身份证的其他证件信息暂不提供授权）
验证方式：因为需要用户主动触发才能发起获取实名信息接口，所以该功能不由 API 来调用，需用 <button> 组件的点击来触发。且需要用户输入微信支付密码验证后，方可算授权。
兼容的微信版本：iOS6.5.22及Android6.5.22 及以上版本
调用必备条件：（1）小程序appid获得内测邀请后提交资质经平台审核通过；（2）小程序开通了微信支付账号；（3）向微信支付工作人员申请证书
开放范围：现为内测邀请阶段，白名单开通。务必需按下述内容，及第三节指引，申请开通权限后再按照接口文档开发，否则无效。
开放说明：
针对小程序的业务方，小程序的主体以及类目，需要在限定的类目范围内。开展的业务也需要是国家相关法规、政策规定的需要“实名办理”的相关业务。
现阶段微信支付实名信息授权接口能力开通的类目限定包含：
-
政务：政府机构或事业单位
-
金融：银行、保险
-
医疗：公立医疗机构
-
运营商
-
教育：公立教育机构
-
交通：航空、客运、网约车、交通卡、共享交通、轨道交通、租车
-
旅游：酒店
-
物流：快递、邮政、物流
三、接口申请
满足第二节中描述的开放类目的小程序，可申请微信支付实名授权接口。请按照如下描述，进行接口申请：
提示：必须完成以下两步的描述才算申请成功。
第一步：邮件申请，开通小程序后台接口能力入口：
申请邮件请发送至腾讯工作邮箱[email protected]。腾讯工作人员会邮件回复资料是否准确无误，并说明是否已开通小程序后台入口。
可通过通过以下路径查看是否已开通入口：通过mp.weixin.qq.com登录小程序，在设置->接口设置中，查看是否有“实名授权”的能力卡片。
邮件申请入口的资料内容如下：
| 微信支付实名信息授权接口内测申请表 |
||
| 序号 |
信息概述 |
具体信息内容 |
| 1 |
业务方名称 |
（服务提供方主体名称） |
| 2 |
使用该接口的场景和用途 |
（用户使用该接口时的场景及服务内容） |
| 3 |
使用该接口的小程序名称及对应appid |
（提供正式服务的小程序） |
| 4 |
商户号 |
（务必是小程序已绑定的商户号） |
| 5 |
日均调用量预估 |
（调用次数、用户数预估） |
| 6 |
最高并发调用量预估 |
（分钟级并发调用次数） |
| 7 |
日并发调用量均值预估 |
（平均分钟级并发调用次数） |
| 8 |
业务方产品联系人姓名、手机、邮箱 |
（请信息提供完全） |
| 9 |
业务方开发联系人姓名、手机、邮箱 |
（请信息提供完全） |
| 10 |
腾讯公司接口人姓名、邮箱 |
（若有，请填写。请信息提供完全，完整姓名和邮箱） |
第二步：线上入口申请权限：
接收到已开通线上入口的邮件回复后。可登录小程序后台，（登录mp.weixin.qq.com的小程序账号，在设置-接口能力中）完成接口权限的申请。包括：
使用类目的配置、填写相关的申请信息等。然后等待线上审核通过。
完成以上两步工作，且线上审核通过后，即可按照后续的接口文档进行开发调用。
四、接口文档
4.1使用方法及参数
使用方法为：
需要将 <button> 组件 open-type 的值设置为 getRealnameAuthInfo，当用户点击并同意之后，可以通过 bindgetRealnameAuthInfo事件回调获取到微信服务器返回的auth_token，再用auth_token调用API来获取用户加密过后的实名信息
示例：
<button open-type="getRealnameAuthInfo" bindgetrealnameauthinfo="authinfo" category-id="{{[99, 904]}}}>实名授权</button>
调用参数为：
| 参数 |
类型 |
说明 |
| open-type |
字符串 |
getrealnameAuthinfo，指定调起实名授权接口 |
| bindgetRealnameAuthInfo |
字符串 |
接口的回调函数 |
| category-id |
数组 |
小程序类目，依次填入一级类目和二级类目 |
4.2获取小程序类目
本节主要描述如何获取授权小程序账号的可选类目
（1）请求方式: get（请使用https协议）
https://api.weixin.qq.com/wxa/get_category?access_token=TOKEN
（2）参数说明
access_token
（3）返回说明（正常时返回的json示例）：
{
"errcode":0,
"errmsg": "ok",
"category_list" : [
{
"first_class":"工具",
"second_class":"备忘录"，
"first_id":1,
"second_id":2,
}
{
"first_class":"教育",
"second_class":"学历教育",
"third_class":"高等"
"first_id":3,
"second_id":4,
"third_id":5,
}
]
}
（4）返回参数说明：
参数 说明
category_list 可填选的类目列表
first_class 一级类目名称
second_class 二级类目名称
third_class 三级类目名称
first_id
一级类目的ID编号
second_id 二级类目的ID编号
third_id 三级类目的ID编号
（5）错误码说明：
返回码 说明
-1 系统繁忙
4.3获取实名信息1说明
根据小程序返回的auth_token获取用户加密过后的实名消息
2使用方法
通过https POST请求，数据为json格式
3请求url
https://api.weixin.qq.com/cgi-bin/wxopen/getrealnameinfo?access_token={access_token}
access_token说明 详见公众号开发文档， api使用的appid必须和小程序的appid保持一致
4请求参数
| 参数 |
类型 |
说明 |
| auth_token |
字符串 |
小程序返回的授权凭证 |
| mch_id |
字符串 |
支付商户号 |
| cert_serialno |
字符串 |
证书序列号（要求大写，详见第五部分） |
| timestamp |
uint32 |
以秒为最小单位的unix时间戳，必须获取当前时间 |
| sign |
字符串 |
请求签名，详见后面关于数据加密的文档 |
5返回参数
| 参数 |
类型 |
说明 |
| encryted_real_name |
字符串 |
加密后的姓名，解密之后数据为GBK格式 |
| encryted_credential_id |
字符串 |
加密后的证件号码 |
示例：
#!/bin/bash
TOKEN='xxxxxxxxxxxx'
URL='https://api.weixin.qq.com/cgi-bin/wxopen/getrealnameinfo'
JSON='{ "auth_token": "xxx", "mch_id": "xxx", "cert_serialno": "xxx", "timestamp": 1234444, "sign": "xxx" }'
curl "${URL}?access_token=${TOKEN}" -d ${JSON}
6返回码
返回码说明：
| 返回码 |
含义 |
| 94001 |
缺少cert_serialno参数 |
| 94002 |
用户未注册微信支付 |
| 94003 |
签名不正确 |
| 94004 |
用户无实名信息 |
| 94005 |
非法的用户token |
| 94006 |
appid未授权获得实名信息 |
| 94007 |
appid与mchid无绑定关系 |
| 94008 |
非法timestamp参数 |
| 94009 |
非法cert_serialno参数，该参数长度为40 |
| 94010 |
非法商户号 |
4.4数据加密文档说明
1说明
由于实名信息属于敏感数据，不能以明文数据传输，所以开发者需要用私钥对请求进行签名(sha256后base64编码).
微信支付会对用户的姓名和身份证信息用开发者的公钥加密 ,开发者可以使用私钥解密出明文. 加密的padding算法为RSA_PKCS1_PADDING
商户号、证书序列号和私钥文件的获取详见第五部分微信支付证书指引
2签名原串
cert_serialno={cert_serialno}×tamp={timestamp}
签名示例
#!/bin/bash
cert_serialno='1234567890'
timestamp=`date +%s`
private_key_file="1900006511_rsa_private_key.pem"
ori_content="cert_serialno=${cert_serialno}×tamp=${timestamp}"
echo $ori_content
sign=`echo -n $ori_content | openssl dgst -sha256 -binary -sign $private_key_file | base64 -w 0`
echo "sign: $sign"
解密示例
#!/bin/sh
encryted_real_name="BtqSM3KOyt+mDhJhyLCS9vsEoo3gTBupZHwS3i8daCyrUGxlEv+k7cE6U+9eiTo2DPNMouZnPSqv5vRERvwvm//JwkKdrV/xvSB4Ak7mJB+/t4Y4lV6gfeyggzN4xtdWoJfkgm0wa4V7oZGrpnexdwYuwyJYTMoz+87qJRwUfWAgF7U7trJ+b5DvCk9Y6KwT0N4j6PtDAk23k0zg06rTANzU3Mq1IWF7LVBcvSvR9nkNAPzcv06LQ70kxqQqVj5z+H+ERuILwBjuIQozCh6pO37Q3slz8UNnl7r48vw7uZe6be1fSDyf0hYE43n2DMpljnATQOMeJxp7nBrsvwDdPQ=="
private_key_file="1900006511_rsa_private_key.pem"
echo -n $encryted_real_name | base64 -d | openssl rsautl -decrypt -ssl -inkey $private_key_file | iconv -f gbk -t utf-8
4.5微信支付商户申请指引
敏感数据需要使用权威CA颁发的API证书来加密。 如果已经获取到了权威CA颁发的API证书，可直接使用。 未获取到的话， 可按下面的方法操作：
1证书申请或升级
登录商户平台申请或者升级到权威CA颁发的证书。
（申请指引：http://kf.qq.com/faq/161222NneAJf161222U7fARv.html
升级指引：http://kf.qq.com/faq/180824BrQnQB180824m6v2yA.html）
2查看证书序列号
登录微信支付商户平台：pay.weixin.qq.com，进入【账户中心】->【账户设置】->【API安全】，点击“查看证书”文字按钮。
点击查看证书，即可看到证书序列号。
五、案例展示
案例：粤省事小程序，实名信息登录。
粤省事小程序是广东省政务一站式服务小程序，为了给用户便捷的体验，使用了微信支付实名授权功能。一方面校验使用者的身份，一方面便捷的获取用户信息，以便为用户提供个性化的政务服务。
具体实现的效果截图如下：