Server-side integration
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.
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 |
|
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 source code
Choose an SDK based on your business needs and technology stack.
Language | SDK download | Source code |
Java | ||
Python | ||
TypeScript | ||
Go | ||
PHP | ||
C# | ||
C++ |
QPS limit
Each API has a QPS limit. For details, see Server-side API QPS limits.
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:
Configure consumption alerts: Set high-value consumption alerts to monitor your spending in real time.
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.
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 |
Model | String | Yes | The liveness detection type. Valid values: Note Custom actions or combinations are not supported.
| PHOTINUS_LIVENESS |
CertType | String | Yes | 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 | https://www.aliyun.com |
MetaInfo | String | Yes | The environment parameter. In a production environment, you must obtain this value by calling the | 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 Important
| 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
| WEB |
CertifyUrlStyle | String | No | The type of CertifyUrl to return. Valid values:
Note If you plan to integrate within a Mini Program, you must set this parameter to | 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.
| url |
RarelyCharacters | String | No | Specifies whether to enable rare characters mode:
| 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:
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:
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.
Note
| 0 |
NeedMultiFaceCheck | String | No | Specifies whether to block verification if the device detects multiple faces. Valid values:
| 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 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 | 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.
| 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
| https://t.aliyun.com/**** |
DescribeFaceVerify
After receiving a callback notification, call this API from your server to retrieve the authentication status and data.
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:
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 |
| If multiple photos are configured to return, the
|
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.
| |
Use the ResultObject.Passed field to determine the authentication result.
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:
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.
Add the following dependencies to your
pom.xmlfile 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>NoteThis 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.
API call examples.
These examples set only the required parameters. For a complete list of parameters, see InitFaceVerify and DescribeFaceVerify.
ImportantThe 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); } }