E-KYC Server-Side SDK Code Examples for App Integration-ID Verification(ID Verification)-阿里云帮助中心

This document provides a sample workflow for integrating the financial-grade real-person authentication solution with your app by using the SDK to call the server-side OpenAPI.

Server-side OpenAPI

InitFaceVerify - Initiate a verification request: Call this API before starting each verification to obtain a CertifyId, which links all API calls within the same verification session.
DescribeFaceVerify - Retrieve verification results: After receiving a callback notification from the client SDK, call this API on the server-side to get the verification status and verification data.

Step 1: Enable the service

To use the Financial-grade Identity Verification Service, you must first enable it. For instructions, see Enable Financial-grade Identity Verification Service.

Step 2: Create and authorize a RAM user

For fine-grained service access management, create a RAM user before you integrate the SDK. Grant the RAM user access to your cloud resources to call service interfaces and obtain OpenAPI access credentials. For instructions on creating a RAM user, granting permissions, and generating an AccessKey, see Authorize a RAM user to access the service.

Step 3: Add an authentication scenario

An authentication scenario defines a specific use case, such as login or payment, where your users complete Real Person Verification using the Financial-grade Real Person Verification service. You can add one or more scenarios and configure different authentication solutions for each. When you call the InitFaceVerify operation to initiate an authentication request, you must pass the authentication scenario ID. To add an authentication scenario and obtain its ID, see Add an Authentication Scenario.

Note

When you add an authentication scenario, you can authorize Alibaba Cloud to access a specified OSS bucket to store verification images. For instructions, see Enable and Authorize OSS Storage.

Step 4: Integrate the SDK

Service endpoints

The following table lists the supported regions and their endpoints.

Important

We recommend configuring primary and secondary endpoints using the code samples in this topic. This enables automatic failover to the secondary endpoint if the primary endpoint fails, ensuring continuous availability for your system.

Region	Service address	VPC address	Global access address
China (Shanghai)	IPv4: cloudauth.cn-shanghai.aliyuncs.com	cloudauth-vpc.cn-shanghai.aliyuncs.com	IPv4: cloudauth.aliyuncs.com IPv6: cloudauth-dualstack.aliyuncs.com
	IPv6: cloudauth-dualstack.aliyuncs.com
China (Beijing)	IPv4: cloudauth.cn-beijing.aliyuncs.com	cloudauth-vpc.cn-beijing.aliyuncs.com
	IPv6: cloudauth-dualstack.cn-beijing.aliyuncs.com

SDK installation and download

Choose an SDK based on your business needs and technology stack.

Language	SDK download	Source code
Java	Download Java SDK	Alibaba Cloud Green SDK for Java
Python	Download Python SDK	Alibaba Cloud Green SDK for Python
TypeScript	Download TypeScript SDK	Alibaba Cloud Green SDK for TypeScript
Go	Download Go SDK	Alibaba Cloud Green SDK for Go
PHP	Download PHP SDK	Alibaba Cloud Green SDK for PHP
C#	Download C# SDK	Alibaba Cloud Green SDK for C#
C++	Download C++ SDK	Alibaba Cloud Green SDK for C++

AccessKey in environment variables

Important

Before you begin, ensure you have an AccessKey and have configured the environment variables:

Write code

The following example uses Java.

Add the following dependency to your pom.xml file to use the SDK in your Maven project.
- The following is the dependency for the Java SDK, which uses the latest version. We recommend that you pin the version number after testing for stability. For SDK versions and examples, see Latest dependency version.
- Before calling the API, you must set the AccessKey in an environment variable. For instructions on how to configure environment variables, see Configure environment variables on Linux, macOS, and Windows.
```
<dependency>
 <groupId>com.aliyun</groupId>
 <artifactId>cloudauth20190307</artifactId>
 <version>LATEST</version> 
</dependency>
```

Sample code

Important

The code examples demonstrate basic API calls and are for illustration only. For production use, optimize and refactor the code to meet your business requirements.

For example, to improve performance, we recommend implementing the singleton pattern for generic objects such as credentialClient, config, and client. The code examples include comments recommending this practice.

InitFaceVerify API call example

import java.util.Arrays;
import java.util.List;

import com.aliyun.cloudauth20190307.Client;
import com.aliyun.cloudauth20190307.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class InitFaceVerify {
    // Use the singleton pattern to improve performance.
    private static com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();

    public static void main(String[] args) throws Exception {

        InitFaceVerifyRequest request = new InitFaceVerifyRequest();
        // Specify the SceneId. The 'L' suffix specifies a Long data type.
        request.setSceneId(0L);
        // Set a unique identifier for the merchant's request.
        request.setOuterOrderNo("xxxx");
        // Authentication solution.
        request.setProductCode("ID_PRO");
        // Mode.
        request.setModel("LIVENESS");
        request.setCertType("IDENTITY_CARD");
        request.setCertName("Mr. Zhang");
        request.setCertNo("xxxx");
        // MetaInfo environment parameter.
        request.setMetaInfo("{}");
        //request.setMobile("130xxxxxxxx");
        //request.setIp("114.xxx.xxx.xxx");
        //request.setUserId("12345xxxx");
        //request.setCallbackUrl("https://www.aliyundoc.com");
        //request.setCallbackToken("xxxxx");
        // To enable encrypted transmission of personal information, uncomment the following lines.
        //request.setEncryptType("SM2");
        //request.setCertName("BCRD/7ZkNy7Q*****M1BMBezZe8GaYHrLwyJv558w==");
        //request.setCertNo("BMjsstxK3S4b1YH*****Pet8ECObfxmLN92SLsNg==");

        // Recommended. This method supports service routing.
        InitFaceVerifyResponse response = initFaceVerifyAutoRoute(request);

        // This method does not support automatic service routing.
        //InitFaceVerifyResponse response = initFaceVerify("cloudauth.cn-shanghai.aliyuncs.com", request);

        response.getBody().getRequestId();
        response.getBody().getResultObject().getCertifyId();
        System.out.println(response.getBody().getRequestId());
        System.out.println(response.getBody().getCode());
        System.out.println(response.getBody().getMessage());
        System.out.println(response.getBody().getResultObject() == null ? null
                : response.getBody().getResultObject().getCertifyId());
    }

    private static InitFaceVerifyResponse initFaceVerifyAutoRoute(InitFaceVerifyRequest request) {
        // The first endpoint is for the primary region, and the second is for the secondary region.
        List<String> endpoints = Arrays.asList("cloudauth.cn-shanghai.aliyuncs.com", "cloudauth.cn-beijing.aliyuncs.com");
        InitFaceVerifyResponse lastResponse = null;
        for (int i=0; i<endpoints.size(); i++) {
            try {
                InitFaceVerifyResponse response = initFaceVerify(endpoints.get(i), request);
                lastResponse = response;

                // If a server-side error occurs, switch to the next region.
                if(response != null){
                    if(500 == response.getStatusCode()){
                        continue;
                    }
                    if(response.getBody() != null){
                        if("500".equals(response.getBody().getCode())){
                            continue;
                        }
                    }
                }

                // Return the response on a successful call.
                return lastResponse;
            }catch (Exception e) {
                e.printStackTrace();
                if(i == endpoints.size()-1){
                    throw new RuntimeException(e);
                }
            }
        }

        return lastResponse;
    }


    private static InitFaceVerifyResponse initFaceVerify(String endpoint, InitFaceVerifyRequest request)
            throws Exception {
        // The AccessKey of an Alibaba Cloud account grants permissions for all APIs. For API access and daily operations, use a RAM user.
        // Do not hardcode the AccessKey ID and AccessKey Secret in your code. This can lead to credential leaks and compromise the security of your resources.
        // This example reads the AccessKey from environment variables by using the Alibaba Cloud Credentials tool for authentication. For more information about how to configure environment variables, see https://help.aliyun.com/document_detail/378657.html.
        // We recommend that you use the singleton pattern.
        Config config = new Config();
        config.setCredential(credentialClient);
        config.setEndpoint(endpoint);
        // Set an http proxy.
        //config.setHttpProxy("http://xx.xx.xx.xx:xxxx");
        // Set an https proxy.
        //config.setHttpsProxy("https://xx.xx.xx.xx:xxxx");
        // We recommend that you use the singleton pattern.
        Client client = new Client(config);

        // Create a RuntimeOptions instance and set runtime options.
        RuntimeOptions runtime = new RuntimeOptions();
        runtime.readTimeout = 10000;
        runtime.connectTimeout = 10000;

        return client.initFaceVerifyWithOptions(request, runtime);
    }

}

DescribeFaceVerify API call example

import java.util.Arrays;
import java.util.List;

import com.aliyun.cloudauth20190307.Client;
import com.aliyun.cloudauth20190307.models.DescribeFaceVerifyRequest;
import com.aliyun.cloudauth20190307.models.DescribeFaceVerifyResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class DescribeFaceVerify {
    // Use the singleton pattern to improve performance.
    private static com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();

    public static void main(String[] args) throws Exception {

        // Create and configure the API request.
        DescribeFaceVerifyRequest request = new DescribeFaceVerifyRequest();
        // Specify the SceneId. The 'L' suffix specifies a Long data type.
        request.setSceneId(0L);

        request.setCertifyId("xxxx");

        // Recommended. This method supports service routing.
        DescribeFaceVerifyResponse response = describeFaceVerifyAutoRoute(request);

        // This method does not support automatic service routing.
        //DescribeFaceVerifyResponse response = describeFaceVerify("cloudauth.cn-shanghai.aliyuncs.com", request);

        System.out.println(response.getBody().getRequestId());
        System.out.println(response.getBody().getCode());
        System.out.println(response.getBody().getMessage());
        System.out.println(
                response.getBody().getResultObject() == null ? null : response.getBody().getResultObject().getPassed());
        System.out.println(
                response.getBody().getResultObject() == null ? null : response.getBody().getResultObject().getSubCode());
        System.out.println(
                response.getBody().getResultObject() == null ? null
                        : response.getBody().getResultObject().getIdentityInfo());
        System.out.println(
                response.getBody().getResultObject() == null ? null
                        : response.getBody().getResultObject().getDeviceToken());
        System.out.println(
                response.getBody().getResultObject() == null ? null
                        : response.getBody().getResultObject().getMaterialInfo());
    }

    private static DescribeFaceVerifyResponse describeFaceVerifyAutoRoute(DescribeFaceVerifyRequest request) {
        // The first endpoint is for the primary region, and the second is for the secondary region.
        List<String> endpoints = Arrays.asList("cloudauth.cn-shanghai.aliyuncs.com", "cloudauth.cn-beijing.aliyuncs.com");
        DescribeFaceVerifyResponse lastResponse = null;
        for (int i = 0; i < endpoints.size(); i++) {
            try {
                DescribeFaceVerifyResponse response = describeFaceVerify(endpoints.get(i), request);
                lastResponse = response;

                // If a server-side error occurs, switch to the next region.
                if (response != null) {
                    if (500 == response.getStatusCode()) {
                        continue;
                    }
                    if (response.getBody() != null) {
                        if ("500".equals(response.getBody().getCode())) {
                            continue;
                        }
                    }
                }

                return lastResponse;
            } catch (Exception e) {
                if (i == endpoints.size() - 1) {
                    throw new RuntimeException(e);
                }
            }
        }

        return lastResponse;
    }


    private static DescribeFaceVerifyResponse describeFaceVerify(String endpoint, DescribeFaceVerifyRequest request)
            throws Exception {
        // The AccessKey of an Alibaba Cloud account grants permissions for all APIs. For API access and daily operations, use a RAM user.
        // Do not hardcode the AccessKey ID and AccessKey Secret in your code. This can lead to credential leaks and compromise the security of your resources.
        // This example reads the AccessKey from environment variables by using the Alibaba Cloud Credentials tool for authentication. For more information about how to configure environment variables, see https://help.aliyun.com/document_detail/378657.html.
        // We recommend that you use the singleton pattern.
        Config config = new Config();
        config.setCredential(credentialClient);
        config.setEndpoint(endpoint);
        // Set an http proxy.
        //config.setHttpProxy("http://xx.xx.xx.xx:xxxx");
        // Set an https proxy.
        //config.setHttpsProxy("https://xx.xx.xx.xx:xxxx");
        // We recommend that you use the singleton pattern.
        Client client = new Client(config);

        // Create a RuntimeOptions instance and set runtime options.
        RuntimeOptions runtime = new RuntimeOptions();
        runtime.readTimeout = 10000;
        runtime.connectTimeout = 10000;

        return client.describeFaceVerifyWithOptions(request, runtime);
    }
}