本文整理自支付宝身份验证产品文档说明，用于个人学习，如有侵权，请联系本人删除文章。

https://docs.open.alipay.com/20181012100420932508 

身份验证产品介绍

支付宝身份验证基于支付宝客户端的实人认证能力，采用多因子认证技术快速得出认证结果；主要解决线上实人开户、帐号实名认证、帐号实人登录等场景中个人身份的识别问题。

与其他实人认证服务相比，本产品使用流程中甚至不需要用户做动作就能快速得出认证结果，速度快、体验好、通过率高，拥有业内独有的眼纹人脸双因子认证技术，安全水平已达金融级要求。

双因子认证技术：两种认证机制相结合的认证技术（多因子认证技术同理）。

认证方案 

 

身份验证接入 

 

第一步：创建应用

 

要在您的应用中接入支付宝身份验证能力，您需要登录支付宝开放平台（open.alipay.com），在开发者中心中创建您的应用，应用审核通过后会生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限。通过 APPID 您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

 

第二步：配置密钥

添加功能并签约

 

应用创建完成后，系统会自动跳转到应用详情页面。开发者可以点击 添加功能 选择 支付宝身份验证 来添加功能。待开发的应用上线后，开发者可以在应用的功能列表点击 签约 以完成特定功能的签约，详情可以参考《使用应用》；支付宝身份验证暂不支持第三方 ISV 代签约开通。

 

配置密钥

 

为了保证交易双方（商户和支付宝）的身份和数据安全，开发者在调用接口前，需要配置双方密钥，对交易数据进行双方校验。RSA 密钥包含应用私钥（APP_PRIVATE_KEY）、应用公钥（APP_PUBLIC_KEY）。生成密钥后，开发者需要在开放平台开发者中心进行密钥配置，配置完成后可以获取支付宝公钥（ALIPAY_PUBLIC_KEY），配置的详细步骤请参考《配置应用环境》。您还可以通过观看快速签名教程学习密钥的配置。

 

说明：

支付宝开放平台 SDK 封装了签名和验签过程，只需配置账号及密钥参数，建议开发者使用。开发者还可以通过自助排查流程和验签教程自助排查配置应用过程中遇到的问题。

 

第三步：集成并配置 SDK

下载服务端 SDK

 

为了帮助开发者调用开放接口，我们提供了开放平台服务端 SDK，包含 JAVA、PHP、NodeJS、Python 和 .NET 五种语言版本，封装了签名&验签、HTTP 接口请求等基础功能。请先下载对应语言版本的 SDK 并引入您的开发工程。请额外引入下列三个 jar 包：

• bcprov-jdk15on-1.62.jar 
•  fastjson-1.2.50.jar 
•  commons-logging-1.1.1.jar

接口调用配置

 

在 SDK 调用前需要进行初始化，以 JAVA 代码为例：

 

AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);

 

关键参数说明：

配置参数	示例值解释	获取方式/示例值
URL	支付宝网关（固定）	https://openapi.alipay.com/gateway.do
APP_ID	APPID即创建应用后生成	获取见上方创建应用
APP_PRIVATE_KEY	开发者应用私钥，由开发者自己生成	获取见配置密钥
FORMAT	参数返回格式，只支持json	json（固定）
CHARSET	请求和签名使用的字符编码格式，支持GBK和UTF-8	开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY	支付宝公钥，由支付宝生成	获取见配置密钥
SIGN_TYPE	商户生成签名字符串所使用的签名算法类型，目前支持 RSA2 和 RSA，推荐使用 RSA2	RSA2

 

接下来，开发者就可以使用 alipayClient 来调用具体的 API 了。alipayClient 只需要初始化一次，后续调用不同的 API 都可以使用同一个 alipayClient 对象。

 

第四步：接口调用

 

支付宝身份验证调用接口的流程如下图所示：

 

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.do
merchantConfigObj.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 client
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayUserCertifyOpenCertifyRequest request = new AlipayUserCertifyOpenCertifyRequest();

//设置certifyId
JSONObject 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&timestamp=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(function() {
  // 需要确保在 AlipayJSBridge ready 之后才调用
  startAPVerify({ 
    certifyId: certifyId, 
    url: url
    }, function(verifyResult) {
    // 认证结果回调触发, 以下处理逻辑为示例代码，开发者可根据自身业务特性来自行处理
    if (verifyResult.resultStatus === '9000') {
      // 验证成功，接入方在此处处理后续的业务逻辑
      // ...
      return;
    }
    
    // 用户主动取消认证
    if (verifyResult.resultStatus === '6001') {
      // 可做下 toast 弱提示
      return;
    }
    
    const errorCode = verifyResult.result && verifyResult.result.errorCode;
    // 其他结果状态码判断和处理 ...
  });
});

 

小程序接入

 

function startAPVerify(options, callback) {
  my.call('startBizService', {
    name: 'open-certify',
    param: JSON.stringify(options),
  }, callback);
}

/**
 * 唤起认证流程
 * 参数: certifyId、url 需要通过支付宝 openapi 开放平台网关接口获取
 * 详细说明可查看文档下方的参数说明
 **/
startAPVerify({ 
  certifyId: certifyId, 
  url: url }, function (verifyResult) {
  // 认证结果回调触发, 以下处理逻辑为示例代码，开发者可根据自身业务特性来自行处理
  if (verifyResult.resultStatus === '9000') {
    // 验证成功，接入方在此处处理后续的业务逻辑
    // ...
    return;
  }
  
  // 用户主动取消认证
  if (verifyResult.resultStatus === '6001') {
    // 可做下 toast 弱提示
    return;
  }

  const errorCode = verifyResult.result && verifyResult.result.errorCode;
  // 其他结果状态码判断和处理 ...
});

注：

• 请将上述示例代码引入小程序的 .js 文件中并传入 certifyId 和 url( 请将上述代码放到 page 外使用或者新建一个 .js 文件，将代码写入新的 .js 文件 )；
• 身份验证功能只支持真机测试，且测试使用的支付宝账号须与 alipay.user.certify.open.initialize 接口中传入的用户保持一致。

 

外部 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 时，业务方需要去支付宝网关接口查询最终状态（由于前端数据是可篡改的）。

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

 

应用接入 

第一步：创建应用

要在您的应用中使用支付宝开放产品的接口能力，您需要先去支付宝开放平台（open.alipay.com），在管理中心中创建登记您的应用，并提交审核，审核通过后会为您生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限，通过APPID您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

 

第二步：添加功能

应用创建完成后，系统会自动跳转到应用详情页面。您可以在 功能列表 中点击 添加功能 来添加“获取会员信息”功能，如下图所示。“获取会员信息”功能无需签约即可使用。

 

 

第三步：配置密钥

开发者调用接口前需要先生成 RSA 密钥，RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY）。生成密钥后在开放平台管理中心进行密钥配置，配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。

 

第四步：搭建和配置开发环境

1. 下载服务端SDK

为了帮助开发者调用开放接口，我们提供了开放平台服务端 SDK，包含 JAVA、PHP、NodeJS、Python 和 .NET 等语言版本，封装了签名&验签、HTTP 接口请求等基础功能。请先下载对应语言版本的 SDK 并引入您的开发工程。

 

2. 接口调用配置

在 SDK 调用前需要进行初始化，以 Java 代码为示例如下：

AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);

 

关键参数说明:

配置参数	示例值解释	获取方式/示例值
URL	支付宝网关（固定）	https://openapi.alipay.com/gateway.do
APPID	APPID 即创建应用后生成	获取见上面创建应用并获取APPID
APP_PRIVATE_KEY	开发者私钥，由开发者自己生成	获取详见上面配置密钥
FORMAT	参数返回格式，只支持 json	json（固定）
CHARSET	编码集，支持 GBK/UTF-8	开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY	支付宝公钥，由支付宝生成	获取详见上面配置密钥
SIGN_TYPE	商户生成签名字符串所使用的签名算法类型，目前支持 RSA2 和 RSA，推荐使用 RSA2	RSA2

 

第五步：调用接口获取用户信息

“获取会员信息”功能根据使用应用类型不同，接口调用流程有所不同：

 

• PC 网页内获取用户信息：通过 URL 拼接得到授权码 auth_code，通过调用 alipay.system.oauth.token 接口获得授权令牌（access_token）和 user_id；开发者通过授权令牌（access_token）调用 alipay.user.info.share 接口获得用户信息。
• 生活号/H5 内获取用户信息：通过调用 JSAPI ap.getAauthCode 接口得到授权码 auth_code，通过调用 alipay.system.oauth.token 接口获得授权令牌（access_token）和 user_id；开发者通过授权令牌（access_token）调用 alipay.user.info.share 接口获得用户信息。

 

申请获取用户信息功能时默认可获取的用户信息包含用户 ID、昵称、性别、省份、城市、用户头像、用户类型、用户状态、是否实名认证、是否是学生等信息。

获取用户信息

 在网页应用内，授权流程如下图所示：

 

1. 按照规则拼接授权页面的 URL 链接，并且引导用户跳转至该链接；
2. 用户在授权页面上确认授权后，将跳转到开发者指定的回调页，并且带上 auth_code；
3. 开发者通过 alipay.system.oauth.token 接口，使用 auth_code 换取 access_token 及用户的 user_id；
4. 如果需要除 user_id 以外的其他信息，则使用 access_token 调用 alipay.user.info.share 接口获得用户信息

 

在生活号或者 H5 应用内，授权流程如下图所示：

 

 

1. 通过调用 JSAPI ap.getAuthCode 接口在当前页面唤起半屏授权浮层；
2. 用户确认授权后，接口返回 auth_code；
3. 开发者通过 alipay.system.oauth.token 接口，使用 auth_code 换取 access_token 及用户的 user_id；
4. 如果需要除 user_id 以外的其他信息，则使用 access_token 调用 alipay.user.info.share 接口获得用户信息。

计费模式

支付宝身份验证产品采用“差额累进”的方式计费，具体计费规则如下表所示。

调用次数	0 < 调用量 ≤ 1000	1000 < 调用量 ≤ 1万	1万 < 调用量 ≤ 10万	10万 < 调用量 ≤ 20万	20万以上
区间费率	1 元/次	0.8 元/次	0.7 元/次	0.6 元/次	0.4 元/次

调用次数：即协议期内成功调用支付宝身份验证服务的总次数。协议期限指合约有限期，一般为一年。

 

计费方式：支付宝身份验证产品采用“差额累进”的计费方式，即按照调用次数划分费率区间，根据不同区间费率分别计算价格，相加之和为最终收费总额。各区间计费规则如上表所示。

 

示例说明：

在合约有效期内，商家将用户的身份信息发给支付宝进行身份验证，无论发送多少次，收费都按实际成功验证次数实时扣取。

1. 如果验证成功900次，则费用金额=900次x1元/次=900元；

2. 如果验证成功1100次，则费用金额=1000次x1元/次+100次x0.8元/次=1080元；

3. 如果验证成功15000次，则费用金额=1000次x1元/次+9000次x0.8元/次+5000次x0.7元/次=11700元