Server-side integration

Updated at:

To integrate the financial-grade ID Verification solution into an H5 page, you need to integrate the server-side SDK on your backend server. This SDK enables you to call the InitFaceVerify API to obtain the CertifyUrl, an authentication URL for browser-based ID Verification. This topic describes the server-side SDK installation, the API parameters, and a sample API call.

Integration

Service endpoint

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

QPS limit

Each API has a QPS limit. For details, see Server-side API QPS limits.

Important

The Financial-grade Real Person Authentication service does not currently support hard caps or automatic suspension based on the number of calls. To control costs and prevent unexpected charges, configure consumption alert rules immediately after integration:

  1. Configure consumption alerts: Set high-value consumption alerts to monitor your spending in real time.

  2. Monitor your resource plan balance: If you have purchased a resource plan, set a resource plan balance alert so you can top up the plan or adjust your call strategy promptly.

  3. Configure business monitoring: See Alert notification settings to monitor for business anomalies and request fluctuations.

Server-side API integration

InitFaceVerify

Call this API before each identity verification to get the verification URL CertifyUrl for use in a browser and a unique CertifyId.

Your web client initiates authentication by calling a business interface that wraps requests to this interface.

Parameters

Parameter

Type

Required

Description

Example

SceneId

Long

Yes

The ID of the authentication scenario. This ID is automatically generated after you create an authentication scenario in the console.

1000000006

OuterOrderNo

String

Yes

A unique business identifier you define for troubleshooting and tracking issues.

It must be a unique 32-character alphanumeric string.

e0c34a77f5ac40a5aa5e6ed20c353888

ProductCode

String

Yes

The authentication solution. Valid value:

  • ID_PRO: With the ID_PRO solution, your users only need to complete liveness detection.

  • ID_PLUS: With the ID_PLUS solution, your users must capture an image of their ID card and complete liveness detection.

    Note

    If your business requires collecting ID card information during verification, choose the ID_PLUS solution.

ID_PRO

Model

String

Yes

The liveness detection type. Valid values:

Note

Custom actions or combinations are not supported.

  • SILENT_LIVENESS: Silent (no action required)

  • LIVENESS (default): blink.

  • PHOTINUS_LIVENESS: blink + photinus liveness detection.

  • MULTI_ACTION: blink + head shake (in random order).

  • MULTI_PHOTINUS: blink + head shake (in random order) + photinus liveness detection.

  • MOVE_ACTION (recommended): proximity movement + blink (in random order).

  • MULTI_FAPTCHA: blink + faptcha.

    Note

    Faptcha verification is an action-based liveness detection method where the user moves their nose tip to follow a pattern. Its randomness enhances security.

PHOTINUS_LIVENESS

CertType

String

Yes

User Document Type.

The value must be IDENTITY_CARD for all supported document types.

IDENTITY_CARD

CertName

String

Yes

The end user's real name.

John Smith

CertNo

String

Yes

The end user's ID number.

330103xxxxxxxxxxxx

ReturnUrl

String

Yes

The URL of the return page where the user is redirected after completing authentication.

Note

For iframe integration, you can pass the fixed value iframe to enable postMessage notifications.

https://www.aliyun.com

MetaInfo

String

Yes

The environment parameter. In a production environment, you must obtain this value by calling the getMetaInfo() function in a JavaScript file. For more information, see Authentication Trigger Page (Start Face Scan).

{
    "appVersion": "1",
    "bioMetaInfo": "4.1.0:1150****,0",
    "appName": "com.aliyun.antcloudauth",
    "deviceType": "ios",
    "osVersion": "iOS 10.3.2",
    "apdidToken": "",
    "deviceModel": "iPhone9,1"
}
Warning

This example is for reference only. Do not use it directly in your integration, otherwise the system will fail to obtain the CertifyUrl.

Mobile

String

No

The end user's mobile number.

130xxxxxxxx

Ip

String

No

The end user's IP address.

47.100.XX.XX

UserId

String

No

A custom user ID. The ID must be unique and can contain up to 100 characters.

123456789

CallbackUrl

String

No

This parameter specifies the callback URL for verification results. The callback method defaults to GET, and the URL must start with https. After verification is complete, the platform invokes this URL and automatically appends the certifyId and passed fields. The passed field returns the subcode value. Example: https://www.aliyun.com?callbackToken=1000004826&certifyId=shaxxxx&passed=200.

Important
  • A callback is triggered only when the verification process is complete, regardless of whether it passed or failed. The system does not send a notification if a user abandons the process, an exception occurs, or the verification is not started. After you receive the callback, call the query API to get detailed verification information.

  • When you make the API call, the system validates that the provided URL is publicly accessible. If the URL is not accessible, the system returns a 401 error.

  • Your callback endpoint must return an HTTP status code of 200. Otherwise, the system retries the callback twice within 3 seconds.

https://www.aliyun.com

CallbackToken

String

No

A security token you generate to prevent replay attacks and data tampering.

If this parameter is set, the CallbackToken field is included in the callback URL.

NMjvQanQgplBSaEI0sL86WnQplB

CertifyUrlType

String

No

The Web SDK device type. Valid values are WEB and H5.

Note
  • Set to WEB for PCs and H5 for mobile devices (phones or tablets).

  • Different algorithms are used for different device types. If you do not set this parameter, the system automatically identifies the device type based on MetaInfo. To ensure algorithm compatibility, set this parameter accurately.

WEB

CertifyUrlStyle

String

No

The type of CertifyUrl to return. Valid values:

  • L: Long URL

  • S (default): Short URL

Note

If you plan to integrate within a Mini Program, you must set this parameter to L (original long URL). For more information, see Third-party mini program integration.

L

AuthId

String

No

The user authorization ID, with a maximum length of 64 characters.

92d46b9e9e2d703f2897f350d5bd4149

EncryptType

String

No

The encryption type. If left empty, no encryption is used.

If you want to enable encrypted transmission, you must specify the encryption algorithm. Currently, only the SM2 national cryptographic algorithm is supported.

If you specify an encryption algorithm, you must encrypt the CertName and CertNo values and pass the resulting ciphertext.

For more information about parameter encryption, see Parameter Encryption Guide.

SM2

ProcedurePriority

String

No

The fallback configuration for mobile H5 authentication when WebRTC or WebAssembly is not compatible.

  • keep: Does not support fallback. The process terminates.

  • url (default): Supports fallback. The system returns an authentication URL, which allows the user to open it in a different browser to complete the authentication.

  • video: Supports fallback. The user records a 3- to 5-second video of themselves blinking using the system camera for authentication.

    Note

    Setting the fallback mode to video disables the following features and reduces the product's security level. We recommend using this mode only for low-security scenarios.

    • The liveness detection type setting will not take effect.

    • The video evidence feature is not supported.

url

RarelyCharacters

String

No

Specifies whether to enable rare characters mode:

  • Y: Enabled

    Before authentication, a dialog box appears, prompting the user to enter their name (containing rare characters) and ID number. The user must agree to the terms to start the authentication process.

  • N: Disabled (default)

Y

UiCustomUrl

String

No

The URL of the UI configuration file.

For a complete list of configurations, see the Web SDK UI Customization Guide.

www.aliyundoc.com

VideoEvidence

String

No

Specifies whether to enable video evidence:

  • true: Enabled

  • false: Disabled (default)

Note

Video files are large. On unstable networks, the system prioritizes essential authentication images and may discard the video file. We recommend you treat video evidence as a weak dependency in your application.

false

CameraSelection

String

No

Specifies whether to enable the camera selection feature:

  • Y: Enabled

  • N: Disabled (default)

Note

This feature applies only to the PC integration mode. When enabled, it allows users to choose their camera for authentication.

N

SuitableType

String

No

This parameter configures the elderly-friendly mode for each verification request. You can set a different value for each request based on your app's business attributes, user demographics, and operational features. The default value is 0.

  • 0: Disable. The elderly-friendly mode is disabled for the current verification request.

  • 1: Enable. The elderly-friendly mode is enabled for the current verification request.

  • 2: User's Choice.

    The end user can select the verification mode. The product's landing page provides two options: "Start Authentication" and "Elderly Mode". If the user selects "Elderly Mode", the system enters the elderly-friendly mode.

Note
  • The elderly-friendly mode parameter takes effect only when the liveness detection type Model is set to LIVENESS or MULTI_ACTION.

  • The elderly-friendly mode enhances usability for elderly users or individuals with physical impairments through features like voice prompts, larger fonts, and an optimized UI.

  • The native SDK supports the elderly-friendly mode in version 2.2.5 and later.

    The web SDK supports the elderly-friendly mode. Use the latest SDK version.

  • Enabling the elderly-friendly mode increases the face verification time.

  • You cannot enable the elderly-friendly mode if the device's system-level accessibility mode is active.

0

NeedMultiFaceCheck

String

No

Specifies whether to block verification if the device detects multiple faces. Valid values:

  • Y: Blocks verification. The client prompts the user to verify again.

  • N (default): Does not block verification. The client sends the largest detected face to the server for a security check.

Y

H5DegradeConfirmBtn

String

No

In fallback mode, specifies whether to display an I have completed the authentication button on the fallback page.

If left empty, the default is N. Clicking this button redirects the user to the specified returnURL and appends the parameters code=1003 and subcode=Z5060.

Note

Guide the user to the appropriate business page based on the authentication result retrieved from the server. We recommend adding a "waiting" status to your authentication result page to handle subcode=Z5060.

Y

EnableAlbumUpload

String

No

Specifies whether users are allowed to upload ID photos from a local album for detection. This feature is available only for the ID_PLUS plan.

  • Y (default): Allowed

  • N: Not allowed

N

Response data

Parameter

Type

Description

Example value

RequestId

String

The request ID.

130A2C10-B9EE-4D84-88E3-5384FF039795

Code

String

The return code. A value of 200 indicates that the request was successful.

For detailed descriptions of different Code values, see Return codes and messages.

200

Message

String

The response message, which provides a brief description of the Code (return code).

success

ResultObject.CertifyId

String

The unique ID for the real-person authentication session.

Important

The CertifyId is used for billing. For future bill reconciliation, store this ID locally.

The CertifyId returned by the initialization API has a 30-minute validity period and can be used for a single submission only.

91707dc296d469ad38e4c5efa6a0f24b

ResultObject.CertifyUrl

String

The URL for performing real-person authentication in a web browser. After authentication is complete, the browser redirects to the URL specified by the ReturnUrl input parameter.

Warning
  • The CertifyUrl returned by the initialization interface is valid for 30 minutes and can be used only once.

  • To receive a CertifyUrl matching the client, provide the MetaInfo parameter correctly. If you cannot obtain the URL, verify that the MetaInfo and other input parameters are correct.

  • The domain name for this URL may change with service updates. To ensure service availability, do not apply access control to this domain name.

  • Avoid using incognito mode or modifying the URL during the browser redirect. Doing so may result in a signature error.

https://t.aliyun.com/****

DescribeFaceVerify

After receiving a callback notification, call this API from your server to retrieve the authentication status and data.

Note

Although InitFaceVerify includes the verification result when it redirects to ReturnUrl, we recommend performing secondary verification by calling this API. This is a necessary security measure because browser data cannot be implicitly trusted.

Request parameters

Parameter

Type

Required

Description

Example value

SceneId

Long

Yes

The ID of the authentication scene.

1000000006

CertifyId

String

Yes

A unique identifier for the real-person authentication.

91707dc296d469ad38e4c5efa6a0f24b

Response data

Parameter

Type

Description

Example value

RequestId

String

The request ID.

130A2C10-B9EE-4D84-88E3-5384FF039795

Code

String

The return code. A value of 200 indicates that the request was successful.

For detailed descriptions of different Code values, see Return codes and messages.

200

Message

String

The response message, which provides a brief description of the Code (return code).

success

ResultObject.Passed

String

The authentication result. Valid values:

  • T: Passed.

  • F: Failed. This includes cases where the user exits the H5 authentication page before completing the face recognition process. The value is never null.

Important

Use this field to determine the authentication result.

T

ResultObject.SubCode

String

A description of the verification result.

For descriptions and troubleshooting suggestions for different status codes, see ResultObject.SubCode error codes.

Note

Use the ResultObject.Passed field to determine the final verification result.

200

ResultObject.IdentityInfo

String

Information about the authenticated subject. This field is typically empty for standard authentication scenarios.

null

ResultObject.DeviceToken

String

The device token.

McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLOxxxxxxx

ResultObject.DeviceRisk

String

The device risk tag.

VirtualBrowser

Note

Multiple device risk tags are separated by commas (,).

For more information about the tags and their meanings, see device risk tags.

ResultObject.MaterialInfo

String

Material information for the face authentication subject:

  • Predicted age and gender from the face image (faceAge/faceGender). Prediction may fail and return no value.

  • Device risk score predicted by device-level algorithms (guardRiskScore). A higher score indicates higher device risk (range: 0–100).

  • Anti-spoofing result and attack score (faceAttack/faceAttackScore)

  • Face occlusion detection result and quality score (faceOcclusion/qualityScore), plus detailed quality fields.

  • Matching score between the face photo and the authoritative source photo (verifyScore).

    Note

    verifyScore is the matching score between the liveness face photo and the authoritative source photo.

    Due to authoritative source adjustments, the authority matching score may not be returned or may be unreliable. It is recommended to rely on the final authentication result (SubCode).

  • OSS storage location and URL of the face photo (video optional).

    Fields for face photo materials and verification video materials are returned based on different configuration items, as follows:

    • The fields related to facial photos (ossBucketName, ossObjectName, pictureUrl) are returned based solely on the configuration in the console authentication scenario:

      • In the console Verification scenario, enable Retain verification materials.

      • OSS authorization is configured and enabled in the console.

    • The video authentication fields (verifyVideoUrl and ossVerifyVideoObjectName) are returned only if all the following conditions are met:

      • In the console Verification scenario, enable Retain verification materials.

      • OSS authorization is configured and enabled in the console.

      • The client configures video return in the extParams parameter (for WebSDK, explicitly configure video-return fields in InitFaceVerify).

    Note

    By default, only the best face photo is returned. To return multiple photos, see Add a verification scenario for configuration.

{
  "faceAttack": "T",
  "faceOcclusion": "F",
  "faceAge":"20",
  "facialPictureFront": {
    "customFaceObjectNameUrls": [
      "https://cn-shanghai-aliyun-cloudauth-177***150.oss-cn-shanghai.aliyuncs.com/verify/177***150/sha58***Pic1.jpeg?Expires=17***9&OSSAccessKeyId=STS.NZtBj***SFWN&Signature=8%2***IKRZFdgsY%3D&security-token=CAIS2w***A%3D",
      "https://cn-shanghai-aliyun-cloudauth-177***150.oss-cn-shanghai.aliyuncs.com/verify/177***150/sha58***Pic2.jpeg?Expires=17***9&OSSAccessKeyId=STS.NZtBj***SFWN&Signature=8%2***IKRZFdgsY%3D&security-token=CAIS2w***A%3D"
    ],
    "customFaceObjectNames": [
      "verify/177***150/sha589b06***Pic1.jpeg",
      "verify/177***150/sha589b06***Pic2.jpeg"
    ],
    "faceAttackScore": 0.00008597839769208804,
    "qualityScore": 99.93476867675781,
    "qualityBackground": "0",
    "qualityBlur": "0",
    "qualityIllu": "0",
    "qualityOccu": "0",
    "qualityWearHat": "F",
    "Gender":"M",
    "verifyScore": 57.678396649466755,
    "ossBucketName": "cn-shanghai-aliyun-cloudauth-12600*********",
    "ossObjectName": "verify/1260***4779/03a08********.jpeg",
    "pictureUrl": "http://cn-shanghai-aliyun-cloudauth-1260***4779.oss-cn-shanghai.aliyuncs.com/verify/1260***4779/03a081********.jpeg?&security-token=CAISjgJ1q6Ft...",
    "ossVerifyVideoObjectName": "verify/1260***4779/03a081****_verifyvideo_dcb7.mov",
    "verifyVideoUrl": "http://cn-shanghai-aliyun-cloudauth-1260***4779.oss-cn-shanghai.aliyuncs.com/verify/1260***4779/03a08150c57__********.mov?security-token=CAISjgJ1q6Ft...",
    "guardRiskScore":20
  }
}

If multiple photos are configured to return, the facialPictureFront field also returns the following:

"customFaceObjectNameUrls": [
  "https://cn-shanghai-aliyun-cloudauth-177***150.oss-cn-shanghai.aliyuncs.com/verify/177***150/sha58***Pic1.jpeg?Expires=17***9&OSSAccessKeyId=STS.NZtBj***SFWN&Signature=8%2***IKRZFdgsY%3D&security-token=CAIS2w***A%3D",
  "https://cn-shanghai-aliyun-cloudauth-177***150.oss-cn-shanghai.aliyuncs.com/verify/177***150/sha58***Pic2.jpeg?Expires=17***9&OSSAccessKeyId=STS.NZtBj***SFWN&Signature=8%2***IKRZFdgsY%3D&security-token=CAIS2w***A%3D"
],
"customFaceObjectNames": [
  "verify/177***150/sha589b06***Pic1.jpeg",
  "verify/177***150/sha589b06***Pic2.jpeg"
]

ResultObject.UserInfo

String

A JSON string with the user's identity information if the entered name contains an uncommon character. This field is empty if the name has no uncommon characters.

  • name: The name entered by the user.

  • verifyName: The final name after encoding and verification. For example, authentication through transcoding may alter a name that contains rare characters, changing 'Wang Xiansheng' to 'Wang Xian'.

  • number: The ID number entered by the user.

{
  "number": "610***********1110",
  "name": "Mr. Wang",
  "verifyName": "Wang"
}
Important

Use the ResultObject.Passed field to determine the authentication result.

Note

If a user abandons authentication by exiting the H5 authentication page before completing the face recognition process, calling DescribeFaceVerify still returns a result. In this case, ResultObject.Passed returns F (the incomplete session is treated as a failed authentication) and ResultObject.SubCode returns the corresponding error code identifying the specific failure reason.

SDK examples

The Alibaba Cloud OpenAPI Portal lets you pre-validate APIs on a webpage or from the command line. Use the following link to start debugging:

Important

Before integrating, ensure you have activated the service and obtained your AccessKey and authentication scenario ID. These parameters are required to call the API. To obtain them, see prerequisites.

SDK integration

Java, for example, requires JDK 1.8 or later.

  1. Add the following dependencies to your pom.xml file to use the SDK in your Maven project.

    • Java SDK dependency. The following version is for reference only. We recommend using the latest dependency version.

      <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>cloudauth20190307</artifactId>
       <version>2.7.2</version>
      </dependency>
    • Authentication dependency. For a list of all released versions, see ChangeLog.txt. We recommend using the latest version.

      <dependency>
         <groupId>com.aliyun</groupId>
         <artifactId>credentials-java</artifactId>
         <version>LATEST</version>
      </dependency>
      Note

      This example uses the Alibaba Cloud Credentials Tool to read the access key from an environment variable for API authentication. You must first configure the environment variable in your system. For instructions, see Configure credentials.

  2. API call examples.

    These examples set only the required parameters. For a complete list of parameters, see InitFaceVerify and DescribeFaceVerify.

    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();
            // The scene ID. The 'L' suffix indicates a Long type.
            request.setSceneId(100000xxxxL);
            // Set a unique identifier for the merchant request.
            request.setOuterOrderNo("xxxx");
            // The authentication solution.
            request.setProductCode("ID_PRO");
            // The verification mode.
            request.setModel("LIVENESS");
            request.setCertType("IDENTITY_CARD");
            request.setCertName("Mr. Zhang");
            request.setCertNo("xxxx");
            // The MetaInfo environment parameter. This should be obtained from the frontend JavaScript and passed in.
            request.setMetaInfo("{}");
            // The return URL for your business page.
            request.setReturnUrl("https://www.aliyundoc.com");
    
            InitFaceVerifyResponse response = initFaceVerifyAutoRoute(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, the second 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 successful response.
                    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 {
            // An AccessKey for an Alibaba Cloud account has permissions to access all APIs. We recommend that you use a RAM user for API access and routine O&M.
            // We strongly recommend that you do not store the AccessKey ID or AccessKey Secret in your project code. Otherwise, the AccessKey may be leaked, which could compromise the security of all resources in your account.
            // This example uses the Alibaba Cloud Credentials Tool to read the access key from an environment variable for API authentication. To configure environment variables, see https://help.aliyun.com/document_detail/378657.html.
            // We recommend the singleton pattern.
            Config config = new Config();
            config.setCredential(credentialClient);
            config.setEndpoint(endpoint);
            // Set the HTTP proxy.
            //config.setHttpProxy("http://xx.xx.xx.xx:xxxx");
            // Set the HTTPS proxy.
            //config.setHttpsProxy("https://xx.xx.xx.xx:xxxx");
            // We recommend 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 an API request and set the parameters.
            DescribeFaceVerifyRequest request = new DescribeFaceVerifyRequest(); 
            // The scene ID. The 'L' suffix indicates a Long type.
            request.setSceneId(0L); 
            // The CertifyId is obtained from the response of the InitFaceVerify API call.
            request.setCertifyId("xxxx");
       
            DescribeFaceVerifyResponse response = describeFaceVerifyAutoRoute(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, the second 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) {
                    e.printStackTrace();
                    if (i == endpoints.size() - 1) {
                        throw new RuntimeException(e);
                    }
                }
            }
    
            return lastResponse;
        }
    
        private static DescribeFaceVerifyResponse describeFaceVerify(String endpoint, DescribeFaceVerifyRequest request)
                throws Exception {
            // An AccessKey for an Alibaba Cloud account has permissions to access all APIs. We recommend that you use a RAM user for API access and routine O&M.
            // We strongly recommend that you do not store the AccessKey ID or AccessKey Secret in your project code. Otherwise, the AccessKey may be leaked, which could compromise the security of all resources in your account.
            // This example uses the Alibaba Cloud Credentials Tool to read the access key from an environment variable for API authentication. To configure environment variables, see https://help.aliyun.com/document_detail/378657.html.
            // We recommend the singleton pattern.
            Config config = new Config();
            config.setCredential(credentialClient);
            config.setEndpoint(endpoint);
            
            // We recommend the singleton pattern.
            Client client = new Client(config);
            
            RuntimeOptions runtime = new RuntimeOptions();
            runtime.readTimeout = 10000;
            runtime.connectTimeout = 10000;
    
            return client.describeFaceVerifyWithOptions(request, runtime);
        }
    }