All Products
Search

This Product

    ID Verification:InitializeV2

    Document Center

    ID Verification:InitializeV2

    Last Updated:Oct 27, 2026

    This topic describes how to call the InitializeV2 operation to initiate a verification request.

    API information

    • API operation: InitializeV2

    • Request method: HTTPS POST

    • Description: Before you start a verification flow, call this operation to obtain a transactionId. This ID is used to associate all API operations for the verification request.

    • QPS limit: Each API has its own QPS limit. For more information, see QPS limits of ID Verification server-side APIs.

    • Endpoints:

      Note

      • Benefits of internal network access: An internal network is a private communication network connecting Alibaba Cloud products within the same region. If your application server is deployed in the same region, use the internal endpoint to access the ID Verification service for enhanced security and stability.

      • Optimizing overseas access: Overseas network environments can be complex. Refer to Optimize server network latency to tune your integration and reduce network latency and request failures.

      Asia Pacific SE 1 (Singapore)

      • Public endpoint: cloudauth-intl.ap-southeast-1.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

      Indonesia

      • Public endpoint: cloudauth-intl.ap-southeast-5.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

      China (Hong Kong)

      • Public endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

      Asia Pacific SE 3 (Kuala Lumpur)

      • Public endpoint: cloudauth-intl.ap-southeast-3.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

    Online debugging and integration

    Note

    Before debugging and integration, read the Use OpenAPI document to learn how to call APIs on the OpenAPI platform and obtain the SDK.

    Go to OpenAPI Explorer to debug this API operation and generate SDK sample code.

    Integration notes

    • A TransactionId is returned only upon successful initialization. The client must complete the authentication within 30 minutes of obtaining the TransactionId or TransactionUrl. The TransactionId is for one-time use only. The ID becomes invalid immediately after the authentication attempt and cannot be reused to invoke the SDK, regardless of whether the authentication succeeds, fails, or is canceled by the user. To start a new authentication, you must request a new TransactionId from the server-side.

    • The TransactionUrl is returned only for the Web SDK scenario and is valid for a single use. Do not concatenate, modify, or reuse it.

    • Due to network latency, CallbackUrl notifications may be delayed. After receiving the authentication completion notification, the client must call the server-side CheckResult operation to obtain the final authentication details. Do not rely solely on the callback notification or the results displayed on the page.

    • The features of the App SDK and Web SDK differ. The behavior of the Web SDK also varies between mobile H5 and PC environments. For more information about supported features, see the integration documents.

    Request parameters

    Description of request fields

    Integration method

    Scenario

    Initialization response

    Request parameters

    App SDK

    Complete verification in a native Android or iOS app

    TransactionId, Protocol

    Common parameters + App-specific parameters

    Web SDK

    Verify in a mobile H5 page, an H5 page embedded in an app, or a PC browser

    TransactionId, TransactionUrl, Protocol

    Common parameters + Web SDK-specific parameters

    The fields are categorized as follows:

    • Common parameters: Applicable to both integration methods.

    • App-specific: Used to customize the liveness detection action flow.

    • Web SDK-specific: Used to control page redirects, language/UI, and H5 fallback behavior.

    Request parameters (Common)

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product code. Set the value to FACE_LIVENESS_PRO.

    FACE_LIVENESS_PRO

    SceneCode

    String

    No

    A custom ID for the authentication scenario. Use this ID to retrieve records from the console. The ID can be a 10-character string that consists of letters, numbers, and underscores.

    1234567890

    MerchantBizId

    String

    Yes

    A unique business identifier for the merchant, used to identify and troubleshoot issues. The identifier is a 32-character string of letters and numbers. The server-side does not validate the uniqueness of this ID. The merchant must ensure that the ID is unique.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    Yes

    Client environment information. Generate this information using the corresponding SDK. If you create it yourself, you must at least pass the correct deviceType value.

    Example code:

    {
  "deviceType": "h5"
}

    Valid values for deviceType:

    • Native Android app: android

    • Native iOS app: ios

    • Embedded H5 page: h5

    • PC web page: web

    Important

    Use the authentication SDK to obtain MetaInfo. This provides more accurate and detailed client information for scenarios such as authentication URL issuance, log investigation, and security checks. If you create a static MetaInfo value, make sure that `deviceType` matches the actual environment. An incorrect value will cause errors when the authentication URL is issued.

    {
  "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"
}

    MerchantUserId

    String

    Yes

    A custom user identifier, or another recognizable user identifier, such as a mobile phone number or email address. We recommend that you desensitize or hash this field.

    123456789

    CallbackUrl

    String

    No

    The callback URL for the authentication result. This URL must start with https. The platform makes a GET request to this URL and appends the transactionId, passed, and subcode parameters.

    The platform returns an HTTP 400 error if the URL is not publicly accessible.

    https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

    CallbackToken

    String

    No

    A custom security token for the merchant. Once set, this token is returned unchanged with the CallbackUrl for anti-replay and tamper-proofing verification.

    NMjvQanQgplBSaEI0sL********

    SecurityLevel

    String

    No

    The security level. Valid values:

    • 01: Normal mode. Recommended for test environments to improve testing efficiency.

    • 02: Secure mode (default). Strongly recommended for production environments.

    02

    Model

    String

    No

    Liveness detection type:

    • SILENT: Silent (Supported by Naive SDK 1.3.6 and later)

    • LIVENESS: Blink (default)

    • PHOTINUS_LIVENESS: Blink and color flash (Not supported in PC mode)

    • TEMPLATE: Custom liveness detection action (Not supported by Web SDK. Supported by Naive SDK 1.3.6 and later.)

    PHOTINUS_LIVENESS

    DocVideo

    String

    No

    Specifies whether to capture a 1- to 2-second evidence video during the face verification process. Valid values:

    • Y: Yes

    • N (default): No

    Video files are large. On unstable networks, the system may discard the video to prioritize uploading essential images.

    To get the video URL, check the Result.ExtFaceInfo.docVideoUrl parameter in the CheckResult response.

    N

    FaceAttributeCheck

    String

    No

    Face Recognition Configuration: Specifies whether to return additional facial attributes.

    • N: No (default)

    • Y: Returns.

    The output is returned in `Checkresult` at Result.ExtFaceInfo.faceAttributeInfo.

    N

    ShowGuidePage

    String

    No

    UI configuration: Show guide page:

    • 1: Show (default)

    • 0: Do not show

    PC mode does not support this configuration.

    Supported in Native SDK version 1.4.0 and above.

    1

    Request parameters (App-specific)

    The following fields are supported only by the native App SDK.

    Name

    Type

    Required

    Description

    Example

    AppQualityCheck

    String

    No

    [Face Scan Configuration] Specifies whether to enable strict face quality detection.

    • Y: Enable (Default)

    • N: Disable

    Supported only in Native SDK v1.2.5 and later. The face quality detection module must be integrated.

    N

    TemplateConfig

    String

    Conditionally required

    [Face Scan Configuration] The custom action pool. This parameter is required when Model is set to TEMPLATE.

    • Configuration rule: Separate multiple action codes with commas.

    • Best practice: A blinking action is required, and the total number of actions must not exceed three.

    Action code lookup table:

    • Blink: 01 (required)

    • Open mouth: 02

    • Shake head left: 03

    • Shake head right: 04

    • Move camera away: 05

    • Move camera closer: 06

    • Color liveness detection: 07

    Supported in Native SDK v1.3.6 and later.

    01,02,07

    TemplateType

    String

    Conditionally required

    [Face Scan Configuration] The execution order of liveness detection actions in TemplateConfig.

    This parameter is required when Model is set to TEMPLATE.

    • Seq: Actions are executed from left to right in the order they are configured in TemplateConfig.

    Supported in Native SDK v1.3.6 and later.

    Seq

    NeedMultiFaceCheck

    String

    No

    [Face Scan Configuration] Determines whether to block the request when multiple faces are detected by the terminal.

    • Y: Block the request and prompt the client to retry face recognition.

    • N: Do not block; select the largest face in the frame and submit it to the server for security verification. (Default)

    Supported in Native SDK version 1.4.1 and above.

    Y

    Request parameters (Web SDK-specific)

    The following fields are supported only by the Web SDK.

    Field

    Type

    Required

    Description

    Example

    LanguageConfig

    String

    No

    A JSON string for the custom language configuration. To apply the settings, convert your configuration to a JSON string based on the provided template and pass it as this parameter. For more information, see Customize Web SDK languages.

    Note

    Supported only in the mobile integration mode of the Web SDK.

    {
  "languageContent": {****},
  "ocrResultContent": {****},
  "supportedLanguage": [****],
  "titleTranslate": {****},
}

    StyleConfig

    String

    No

    A JSON string for the custom UI configuration. To apply the configuration, convert your settings to a JSON string based on the provided template and pass it as this parameter. For more information, see Customize IDV UI styles.

    Note

    Supported only in the mobile integration mode of the Web SDK.

    {
  "guidepage:": {****}, 
  "ocrPage": {****},
  "ocrResultPage": [****],
  "facePage": {****},
}

    ReturnUrl

    String

    Conditionally required

    The URL to redirect to after authentication. This is optional for the iframe embedded pattern. Provide this URL for page redirect scenarios that do not use an iframe.

    https://www.alibabacloud.com

    ProcedurePriority

    String

    No

    Specifies whether to display a fallback method when a compatibility issue occurs during mobile H5 authentication.

    • url: Supports fallback. The page displays the authentication URL. Users can copy the URL and open it in a different browser to continue authentication. (Default)

    • keep: Does not support fallback. An error reason is returned, and the authentication flow ends. This option is not supported on PCs. Recommended for webpages embedded in an app.

    url

    Returned data

    Differences in returned fields

    Field

    App SDK

    Web SDK

    Note

    RequestId / Code / Message

    Yes

    Yes

    General response information.

    Result.TransactionId

    Yes

    Yes

    This is the unique identifier for the authentication flow, a field for billing statistics, and a request parameter for the CheckResult operation. Attach this identifier to the merchant business ID and store it only on the server-side.

    Result.Protocol

    Yes

    Yes

    Standard authentication and encryption protocol. Pass this through to the client SDK. The Web SDK requires this field for iframe embedding.

    Result.TransactionUrl

    No

    Yes

    The Web SDK authentication URL. After authentication, it redirects to the ReturnUrl. This URL cannot be modified and can be accessed only once. You must complete the authentication within 30 minutes of obtaining the URL or TransactionId.

    Name

    Type

    Description

    Example

    HTTP Status Code

    Integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    String

    The request ID.

    130A2C10-B9EE-4D84-88E3-5384FF03****

    Code

    String

    The return code. For more information, see Server-side HTTP status codes.

    Success

    Message

    String

    A detailed description of the return code.

    success

    Result.TransactionId

    String

    A unique identifier for the authentication flow. This identifier is used for billing and is required for calls to the CheckResult API.

    Important

    • The init API does not return a TransactionId if the request fails, for example, due to an invalid parameter.

    • Bind the TransactionId to your business process ID and store it on the server-side. When calling the CheckResult API, retrieve this ID from your server-side storage.

    • The TransactionId or TransactionUrl is valid for 30 minutes. You must complete the authentication within this period, after which the ID expires.

    hksb7ba1b28130d24e015d6********

    Result.TransactionUrl

    String

    The Web SDK verification URL. After verification, the page redirects according to the input parameter ReturnUrl.

    Important

    • Do not modify the TransactionUrl during the integration process. Doing so will cause a verification exception.

    • The TransactionUrl is for single use only. Reusing it will cause a verification exception.

    • After you obtain the TransactionId or TransactionUrl, you have 30 minutes to complete the verification before the ID or URL expires.

    https://www.alibabacloud.com/index.html?clientcfg=****

    Result.Protocol

    String

    The encrypted string for the standard authentication protocol.

    Passing this parameter to the client SDK reduces network interactions and supports dynamic network switching, which improves the user experience.

    hksb7ba1b28130d24e015d*********

    Request examples

    App SDK

    Minimum request example

    {
  "ProductCode": "FACE_LIVENESS_PRO",
  "MerchantBizId": "e0c34a77f5ac***e6ed20c35",
  "MetaInfo": "{\"deviceType\":\"android\"}",
  "MerchantUserId": "user_hash_value"
}

    Complete request example

    {
  "ProductCode": "FACE_LIVENESS_PRO",
  "SceneCode": "SCENE_001",
  "MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
  "MetaInfo": "{\"zimVer\":\"3.0.0\",\"appVersion\":\"1\",\"bioMetaInfo\":\"4.1.0:1150****,0\",\"appName\":\"com.aliyun.antcloudauth\",\"deviceType\":\"android\",\"osVersion\":\"Android 12\",\"apdidToken\":\"\",\"deviceModel\":\"Pixel 6\"}",
  "MerchantUserId": "user_hash_value_12345",
  "CallbackUrl": "https://www.example.com/callback",
  "CallbackToken": "NMjvQanQgplBSaEI0sL********",
  "SecurityLevel": "02",
  "Model": "TEMPLATE",
  "DocVideo": "Y",
  "FaceAttributeCheck": "Y",
  "ShowGuidePage": "1",
  "AppQualityCheck": "Y",
  "TemplateConfig": "01,02,07",
  "TemplateType": "Seq",
  "TemplateRanCount": "2"
}

    Web SDK

    Minimum request example

    {
  "ProductCode": "FACE_LIVENESS_PRO",
  "MerchantBizId": "e0c34a77f5a***6ed20c35",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value",
  "ReturnUrl": "https://example.com/liveness/result"
}

    Complete request example

    {
  "ProductCode": "FACE_LIVENESS_PRO",
  "SceneCode": "SCENE_001",
  "MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value_12345",
  "CallbackUrl": "https://www.example.com/callback",
  "CallbackToken": "NMjvQanQgplBSaEI0sL********",
  "SecurityLevel": "02",
  "Model": "PHOTINUS_LIVENESS",
  "DocVideo": "N",
  "FaceAttributeCheck": "N",
  "LanguageConfig": "{\"languageContent\":{},\"ocrResultContent\":{},\"supportedLanguage\":[\"zh-CN\"],\"titleTranslate\":{}}",
  "StyleConfig": "{\"guidepage\":{},\"ocrPage\":{},\"ocrResultPage\":[],\"facePage\":{}}",
  "ShowGuidePage": "1",
  "ReturnUrl": "https://www.example.com/liveness/result",
  "ProcedurePriority": "url"
}