Server-side call to the InitFaceVerify API in app integration scenarios to initiate an ID Verification for Financial Services request-ID Verification(ID Verification)-阿里云帮助中心

This topic describes how to call the InitFaceVerify API to initiate a request for ID Verification for Financial Services.

Initiate verification request

API operation: InitFaceVerify

Global endpoint: cloudauth.aliyuncs.com (IPv4) or cloudauth-dualstack.aliyuncs.com (IPv6)

Request method: POST and GET

Transport protocol: HTTPS

Description: Call this API before each verification to obtain a CertifyId, which links all API calls for a single authentication request.

QPS limit: Each API has a dedicated limit. 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:

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.

Request parameters

Name	Type	Required	Description	Example
SceneId	Long	Yes	The ID of the verification scenario to use. This ID is automatically generated after you create a verification scenario in the console. For instructions on creating a scenario, see Add a verification scenario.	100000****
OuterOrderNo	String	Yes	Your custom unique business identifier, used for troubleshooting later. Use up to 32 alphanumeric characters. Ensure it is unique.	e0c34a77f5ac40a5aa5e6ed20c35****
ProductCode	String	Yes	The verification solution to use. Valid values: 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	No	The type of liveness detection. The following values are supported: Note Only the following values are supported for the liveness detection type. Custom actions or combinations are not supported. SILENT_LIVENESS: Silent (no action) LIVENESS (default): Blink PHOTINUS_LIVENESS: Blink + Color flash MULTI_ACTION: Blink + Shake head (The order of actions is random) MOVE_ACTION: Move closer and farther away + Blink MULTI_PHOTINUS: Blink + Shake head (The order of actions is random) + Color flash MOVE_PHOTINUS: Move closer and farther away + Color flash Note The default liveness detection type is supported by the following SDK versions: Android SDK 1.2.6 and later iOS SDK 1.2.4 and later Harmony SDK 1.0.0 and later Other types are supported by the latest SDK versions for Android, iOS, and Harmony. Use the latest SDK version.	MOVE_ACTION
CertType	String	Yes	This parameter specifies the user's identity document type. For supported document types, see solution overview. The value is IDENTITY_CARD for all document types. Note When ProductCode is ID_PLUS, CertType is optional.	IDENTITY_CARD
CertName	String	Yes	The end user's real name. Note When ProductCode is ID_PLUS, CertName is optional.	ZhangXX
CertNo	String	Yes	The certificate number of the end user. Note When ProductCode is ID_PLUS, CertNo is optional.	330103************
MetaInfo	String	Yes	Environment parameters from MetaInfo, which you must obtain using the client SDK. For details, see App (SDK) integration.	`{ "zimVer": "3.0.0", "appVersion": "1", "bioMetaInfo": "4.1.0:1150**,0", "appName": "com.aliyun.antcloudauth", "deviceType": "ios", "osVersion": "iOS 10.3.2", "apdidToken": "", "deviceModel": "iPhone9,1" }` Note** This example is for reference only. Do not use it directly in your integration. Follow the SDK integration guide for accurate implementation.
Mobile	String	No	The end user's mobile phone number.	130********
Ip	String	No	The end user's IP address.	114.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 yourself to prevent replay attacks and tampering. If you set this value, the callback URL includes the CallbackToken field.	NMjvQanQgplBSaEI0sL86WnQplB
AuthId	String	No	User authorization ID. Maximum length is 64 characters.	92d46b9e9e2d703f2897f350d5bd4149
EncryptType	String	No	The encryption algorithm to use. Only the SM2 Chinese cryptographic algorithm is supported. After enabling encrypted transmission, pass the encrypted CertName and CertNo. For encryption instructions, see Parameter encryption.	SM2
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
RarelyCharacters	String	No	Enable rare character mode: Y: Enable Before verification, users see an input box where they must enter their name and ID number containing rare characters and accept the terms before starting verification. N: Disable (default) Note Rare character mode is only supported for ID Verification for Financial Services in app, PC, and H5 integration scenarios. Other solutions do not support it.	Y
AppQualityCheck	String	No	Specifies whether to enable the strict face quality check in the SDK. Y: Enable N: Disable (default) Note If you enable this parameter, the SDK must integrate the strict face quality check module. In common occlusion scenarios, such as wearing a hat, mask, or sunglasses, the client prompts the user to try again. This ensures that a high-quality face image is captured before verification. Enabling this check might reduce the face verification success rate. Android SDK 2.3.24 or later is required.	N
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
enableBeauty	String	No	Enable retouching during face verification. Y: Enable N (default): Disable Important The parameter takes effect only when the SDK has fully integrated the module version. Enabling retouching does not affect the quality of stored face images. This feature is currently supported only on Android and iOS SDKs.	N

Response data

Name	Type	Description	Example
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 ID Verification. Pass this parameter when the client calls the verify function to start verification. Important The CertifyId field is used for billing. Store this value locally to reconcile your bills later. The CertifyId returned by the initialization API is valid for 30 minutes and can be used for only one verification submission. Use it within this period and avoid reuse.	91707dc296d469ad38e4c5efa6a0****

FAQ

Can the InitFaceVerify interface be called directly from the client?

The InitFaceVerify interface is for server-side use only and cannot be called directly from the client. In a standard flow, your business server calls the InitFaceVerify interface to obtain a CertifyId. The server then passes this CertifyId to the client software development kit (SDK) to start the authentication. This architecture ensures that your business flow is secure and controllable. It prevents the client from bypassing your server-side business logic to initiate a comparison.

Does the multi-action liveness detection mode require a separate purchase?

The multi-action liveness detection mode does not require a separate purchase. To enable this mode, set the `Model` parameter to the corresponding value, such as `MULTI_PHOTINUS`, when you call the InitFaceVerify interface. The billing for this mode is the same as for other liveness detection types. No extra fees are charged.

Does ID Verification for Financial Services require separate steps for two-factor authentication and facial recognition?

ID Verification for Financial Services uses a single interface, InitFaceVerify, to perform a three-factor authentication that combines name, ID card number, and facial recognition. Separate integration steps are not required. You can call the InitFaceVerify interface and pass the `CertName` (name), `CertNo` (ID card number), and `MetaInfo` (device information) parameters to complete the end-to-end validation.

Why do I get a match result when the uploaded photo does not match the ID card?

If you receive a match result even when the uploaded photo does not match the ID card information, you are likely using the wrong interface. The liveness detection interface, which has a `ProductCode` of `LR_FR`, only verifies that a real person is performing the operation. It does not compare the face with the ID card information. To verify that the face matches the ID card, use the ID Verification for Financial Services interface. Select the correct `ProductCode` based on your business scenario:

ID_PRO: For scenarios that require only liveness detection, the system automatically compares the captured face with the provided identity information.
ID_PLUS: Use this for scenarios that require capturing the ID card information. The user must take a photo of their ID card and complete the liveness detection.