支付宝身份验证调用接口的流程如下图所示:
1. 初始化身份认证单据号
准备接口必要参数,通过 alipay.user.certify.open.initialize 接口调用身份认证初始化服务,以下代码以 Java 语言为例。
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");AlipayUserCertifyOpenInitializeRequest request = new AlipayUserCertifyOpenInitializeRequest();//构造身份信息json对象JSONObject identityObj = new JSONObject();//身份类型,必填,详细取值范围请参考接口文档说明identityObj.put("identity_type", "CERT_INFO");//证件类型,必填,详细取值范围请参考接口文档说明identityObj.put("cert_type", "IDENTITY_CARD");//真实姓名,必填identityObj.put("cert_name", "张三");//证件号码,必填identityObj.put("cert_no", "260104197909275964");//构造商户配置json对象JSONObject merchantConfigObj = new JSONObject();// 设置回调地址,必填. 如果需要直接在支付宝APP里面打开回调地址使用alipay协议,参考下面的案例:appId用固定值 20000067,url替换为urlEncode后的业务回跳地址// alipays://platformapi/startapp?appId=20000067&url=https%3A%2F%2Fapp.cqkqinfo.com%2Fcertify%2FzmxyBackNew.domerchantConfigObj.put("return_url", "alipays://platformapi/startapp?appId=20000067&url=https%3A%2F%2Fapp.cqkqinfo.com%2Fcertify%2FzmxyBackNew.do");//构造身份认证初始化服务业务参数数据JSONObject bizContentObj = new JSONObject();//商户请求的唯一标识,推荐为uuid,必填bizContentObj.put("outer_order_no", "506608c8141a4fc781538fb3e55029f9");bizContentObj.put("biz_code", "FACE");bizContentObj.put("identity_param", identityObj);bizContentObj.put("merchant_config", merchantConfigObj);request.setBizContent(bizContentObj.toString());//发起请求AlipayUserCertifyOpenInitializeResponse response = alipayClient.execute(request);if (response.isSuccess()) { System.out.println("调用成功"); //接口调用成功,从返回对象中获取certify_id String certifyId = response.getCertifyId(); //执行后续流程...} else { System.out.println("调用失败");}
2. 生成认证服务请求地址
将生成的 certify_id 作为入参,调用身份认证开始认证服务接口 alipay.user.certify.open.certify,以下代码以 Java 语言为例。
- 生成认证请求URL
//参考代码如下://获取alipay clientAlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");AlipayUserCertifyOpenCertifyRequest request = new AlipayUserCertifyOpenCertifyRequest();//设置certifyIdJSONObject bizContentObj = new JSONObject();bizContentObj.put("certify_id", "2109b5e671aa3ff2eb4851816c65828f");request.setBizContent(bizContentObj.toString());//生成请求链接,这里一定要使用GET模式AlipayUserCertifyOpenCertifyResponse response = alipayClient.pageExecute(request, "GET");if(response.isSuccess()){System.out.println("开始认证服务调用成功");String certifyUrl = response.getBody();//执行后续流程...} else {System.out.println("调用失败");}
- 生成如下的认证URL样例
https://openapi.alipay.com/gateway.do?alipay_sdk=alipay-sdk-java-dynamicVersionNo&app_id=2015111100758155&biz_content=%7B%22certify_id%22%3A%22ZM201611253000000121200404215172%22%7D&charset=GBK&format=json&method=alipay.user.certify.open.certify&sign=MhtfosO8AKbwctDgfGitzLvhbcvi%2FMv3iBES7fRnIXn%2BHcdwq9UWltTs6mEvjk2UoHdLoFrvcSJipiE3sL8kdJMd51t87vcwPCfk7BA5KPwa4%2B1IYzYaK6WwbqOoQB%2FqiJVfni602HiE%2BZAomW7WA3Tjhjy3D%2B9xrLFCipiroDQ%3D&sign_type=RSA2×tamp=2016-11-25+15%3A00%3A59&version=1.0&sign=MhtfosO8AKbwctDgfGitzLvhbcvi%2FMv3iBES7fRnIXn%2BHcdwq9UWltTs6mEvjk2UoHdLoFrvcSJipiE3sL8kdJMd51t87vcwPCfk7BA5KPwa4%2B1IYzYaK6WwbqOoQB%2FqiJVfni602HiE%2BZAomW7WA3Tjhjy3D%2B9xrLFCipiroDQ%3D
3. 根据不同接入方式唤起身份验证页面
H5 页面接入
function ready(callback) { // 如果jsbridge已经注入则直接调用 if (window.AlipayJSBridge) { callback && callback(); } else { // 如果没有注入则监听注入的事件 document.addEventListener('AlipayJSBridgeReady', callback, false); }}// startBizService 接口仅在支付宝 10.0.15 及以上支持// 需要接入者自行做下版本兼容处理 !!function startAPVerify(options, callback) { AlipayJsBridge.call('startBizService', { name: 'open-certify', param: JSON.stringify(options), }, callback);}/** * 唤起认证流程 * 参数: certifyId、url 需要通过支付宝 openapi 开放平台网关接口获取 * 详细说明可查看文档下方的参数说明 **/ready(() => { // 需要确保在 AlipayJsBridge ready 之后才调用 startAPVerify({ certifyId, url }, verifyResult => { // 认证结果回调触发, 以下处理逻辑为示例代码,开发者可根据自身业务特性来自行处理 if (verifyResult.resultStatus === '9000') { // 验证成功,接入方在此处处理后续的业务逻辑 // ... return; } // 用户主动取消认证 if (verifyResult.resultStatus === '6001') { // 可做下 toast 弱提示 return; } const errorCode = verifyResult.result && verifyResult.result.errorCode; // 其他结果状态码判断和处理 ... });});
小程序接入
要使用小程序接入身份验证功能,开发者需要完成以下两步操作:
步骤一:调用小程序向外跳转 H5 的 API,代码示例如下:
my.ap.navigateToAlipayPage({ //url的获取参考本文档“2.生成认证服务请求地址” path: encodeURIComponent(url) })
步骤二:步骤一的操作将会唤起实人认证页面,执行认证流程,认证结束后,会回调前置条件入参中指定的回调地址。详情可参考小程序 my.ap.navigateToAlipayPage 接口文档。
注意:
调用身份验证的小程序必须是以企业主体注册的,个人用户申请的小程序暂不支持。
外部 H5 唤起支付宝客户端进行实名认证
- 要在您的 App 中唤起支付宝客户端,需要额外在实名认证 url 上拼接唤端逻辑(即
alipays://platformapi/startapp?appId=20000067&url=
),因此您最终跳转实名认证的 url 应该是:
//url的获取参考本文档“2.生成认证服务请求地址”const certifyUrl = alipays://platformapi/startapp?appId=20000067&url=encodeURIComponent(url);
- 在您的页面中可以通过
location.href=certifyUrl
唤起支付宝并进入实名认证流程;此操作将会唤起实人认证页面,执行认证流程,认证结束后,会回调前置条件入参中指定的回调地址。
4. 验证本次认证结果
入参 options
{String} certifyId
- 认证订单标识符,通过 alipay.user.certify.open.initialize 获取{String} url
- 支付宝开放平台网关 URL,通过 alipay.user.certify.open.certify 获取
回调函数出参
- 回调函数带入的参数
verifyResult: { resultStatus: 'xx', result: { } }
名称 | 类型 | 描述 |
---|---|---|
resultStatus | string | 认证流程结果状态码, 详见以下 ResultStatus 定义 |
result.certifyId | string | 本次认证流水号 certifyId |
result.errorCode | string | 业务异常错误码 |
注意:
result 对象可能为 null, API 接入者代码逻辑需要做防御性处理,避免 NPE 异常。
ResultStatus
状态码 | 描述 |
---|---|
9000 | 认证通过 |
6002 | 网络异常 |
6001 | 用户取消了业务流程,主动退出 |
4000 | 业务异常 |
注意:
- resultStatus = 6001、6002 时,result 对象数据为空,接入者不需要获取 result 对象数据。
- resultStatus= 9000 时,业务方需要去支付宝网关接口查询最终状态(由于前端数据是可篡改的),查询代码如下:
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");AlipayUserCertifyOpenQueryRequest request = new AlipayUserCertifyOpenQueryRequest();//设置certifyIdJSONObject bizContentObj = new JSONObject();//certifyId是初始化接口返回bizContentObj.put("certify_id", "2109b5e671aa3ff2eb4851816c65828f");request.setBizContent(bizContentObj.toString());AlipayUserCertifyOpenQueryResponse response = alipayClient.execute(request);if(response.isSuccess()){ System.out.println("开始认证服务调用成功"); String certifyUrl = response.getBody(); //执行后续流程...} else { System.out.println("调用失败");}
Status:4000
包含的部分 errorCode 如下表格所示
错误码 | 描述 |
---|---|
UNKNOWN_ERROR | 未知异常 |
SYSTEM_ERROR | 系统异常 |
USER_IS_NOT_CERTIFY | 用户未认证 |
... | 其他 |
接入注意
此文档只适用于支付宝客户端App内接入使用
H5页面接入时,需要接入者执行判断当前支付宝客户端版本号,做好 startBizService 版本兼容处理
支付宝版本号获取
const matchResult = window.navigator.userAgent.match(/AliApp(AP/([d.]+))/i);const apVersion = (matchResult && matchResult[1]) || ''; // 如: 10.1.58.00000170
转载自:(支付宝)https://docs.open.alipay.com/20181012100420932508/quickstart/