接口时序图

接入步骤

说明：此文档只适用于支付宝客户端 App 内接入使用。

初始化身份认证

准备接口必要参数，调用 alipay.user.certify.open.initialize（身份认证初始化服务接口）初始化服务获取 certifyId（认证流程号）。

说明：港澳台同胞身份验证服务仅支持在支付宝客户端内使用，外部 APP 使用该项服务需唤起支付宝客户端。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayUserCertifyOpenApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayUserCertifyOpenApiInitialize {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayUserCertifyOpenApi api = new AlipayUserCertifyOpenApi();
        AlipayUserCertifyOpenInitializeModel data = new AlipayUserCertifyOpenInitializeModel();
        data.setBizCode("FACE");
        data.setOuterOrderNo("ZGYD201809132323000001234");
        OpenCertifyMerchantConfig merchantConfig = new OpenCertifyMerchantConfig();
        merchantConfig.setFaceReserveStrategy("reserve");
        merchantConfig.setReturnUrl("https://xxx");
        data.setMerchantConfig(merchantConfig);
        OpenCertifyIdentityParam identityParam = new OpenCertifyIdentityParam();
        identityParam.setCertNo("260104197909275964");
        identityParam.setIdentityType("CERT_INFO");
        identityParam.setCertType("IDENTITY_CARD");
        identityParam.setCertName("张三");
        data.setIdentityParam(identityParam);
        try {
            AlipayUserCertifyOpenInitializeResponseModel response = api.initialize(data);
        } catch (ApiException e) {
            AlipayUserCertifyOpenInitializeDefaultResponse errorObject = (AlipayUserCertifyOpenInitializeDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

重要入参说明

identity_param：需要验证的身份信息参数，格式为 json。

identity_type：身份信息参数类型，必填，必须传入 CERT_INFO 。

cert_type：证件类型，必填，当前支持：

IDENTITY_CARD：身份证。

HOME_VISIT_PERMIT_HK_MC：港澳居民来往内地通行证。

HOME_VISIT_PERMIT_TAIWAN：台湾居民来往内地通行证。

RESIDENCE_PERMIT_HK_MC：港澳居民居住证。

RESIDENCE_PERMIT_TAIWAN：台湾居民居住证。

cert_name：真实姓名，必填，填写需要验证的真实姓名，与证件类型对应。

cert_no：证件号码，必填，填写需要验证的证件号码，与证件类型对应。

merchant_config：商户个性化配置，必填，格式为json。支持：

return_url：需要回跳的目标地址，必填，一般指定为商户业务页面。

biz_code：认证场景码。入参支持的认证场景码和商户签约的认证场景相关，取值如下：

FACE：多因子人脸认证。

CERT_PHOTO：多因子证照认证。

CERT_PHOTO_FACE ：多因子证照和人脸认证。

SMART_FACE：多因子快捷认证。

生成认证服务请求地址

开发者将生成的 certify_id 作为入参，调用 alipay.user.certify.open.certify（身份认证开始认证接口）获取认证地址 URL。

示例代码

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayUserCertifyOpenCertifyRequest request = new AlipayUserCertifyOpenCertifyRequest();
request.setBizContent("{" +
"  \"certify_id\":\"OC201809253000000393900404029253\"" +
"}");
AlipayUserCertifyOpenCertifyResponse response = alipayClient.pageExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} 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

唤起身份验证页面

小程序接入支付宝身份验证产品可查看 小程序接入流程。

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 ;
      // 其他结果状态码判断和处理 ... 
   });
});

外部 H5 唤起支付宝客户端进行实名认证

要在商户的 H5 中唤起支付宝客户端，需要额外在实名认证 url 上拼接唤端逻辑（即 alipays://platformapi/startapp?appId=20000067&url=），因此商户最终跳转实名认证的 url 应该是：

//url的获取参考本文档“2.生成认证服务请求地址”
const   certifyUrl   =   alipays://platformapi/startapp?appId=20000067&url=encodeURIComponent(url);

在商户 H5 页面中可以通过 location.href=certifyUrl 唤起支付宝并进入实名认证流程；此操作将会唤起实人认证页面，执行认证流程，认证结束后，会回调前置条件入参中指定的回调地址。

验证本次认证结果

入参 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= 9000 ，业务方需要去支付宝网关接口查询最终状态，避免前端数据篡改的风险。

resultStatus = 6001、6002 时，result 对象数据为空，接入者不需要获取 result 对象数据。

Status：4000

包含的部分 errorCode 如下表格所示。

错误码	描述
UNKNOWN_ERROR	未知异常。
SYSTEM_ERROR	系统异常。
USER_IS_NOT_CERTIFY	用户未认证。
...	其他。

查询身份认证结果

开发者可调用 alipay.user.certify.open.query（身份认证记录查询接口），查询认证状态和相关数据。

示例代码

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayUserCertifyOpenApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayUserCertifyOpenApiQuery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayUserCertifyOpenApi api = new AlipayUserCertifyOpenApi();
        String certifyId = "OC201809253000000393900404029253";
        try {
            AlipayUserCertifyOpenQueryResponseModel response = api.query(certifyId);
        } catch (ApiException e) {
            AlipayUserCertifyOpenQueryDefaultResponse errorObject = (AlipayUserCertifyOpenQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

重要参数说明

certify_id：必填，身份识别申请单 ID。通过 alipay.user.certify.open.initialize（身份认证初始化服务接口）同步响应获取。

响应示例

{
    "material_info":"{}",
    "passed":"T",
    "fail_reason":"Z1147",
    "identity_info":"{}"
}

重要响应说明

passed：是否通过认证。

T：通过。

F：未通过。

fail_reason：错误原因，扩展字段，默认不返回。

更多接口参数及响应详情参见 alipay.user.certify.open.query（身份认证记录查询）。

服务端 SDK 接入流程

接口时序图#

接入步骤#

初始化身份认证#

示例代码#

重要入参说明#

生成认证服务请求地址#

示例代码#

认证 URL 示例#

唤起身份验证页面#

H5 页面接入#

外部 H5 唤起支付宝客户端进行实名认证#

验证本次认证结果#

入参 options#

回调函数出参#

查询身份认证结果#

示例代码#

重要参数说明#

响应示例#

重要响应说明#

接口时序图

接入步骤

初始化身份认证

示例代码

重要入参说明

生成认证服务请求地址

示例代码

认证 URL 示例

唤起身份验证页面

H5 页面接入

外部 H5 唤起支付宝客户端进行实名认证

验证本次认证结果

入参 options

回调函数出参

查询身份认证结果

示例代码

重要参数说明

响应示例

重要响应说明