All Products
Search

This Product

    ID Verification:InitializeV2

    Document Center

    ID Verification:InitializeV2

    Last Updated:Jul 10, 2026

    This topic describes how to call the Initialize operation to initiate an electronic Know Your Customer (eKYC) request.

    Initiate a verification request

    • API operation: InitializeV2

    • Method: HTTPS POST

    • Description: Before you start each eKYC verification process, call this API to obtain a transactionId and a transactionUrl. These parameters link the API calls for a single verification request.

    • QPS limit: Each API has a dedicated QPS limit. For details, see QPS limits of ID Verification server-side APIs.

    • Service endpoints:

      Note

      • Benefits of internal network access: An internal network enables private communication between Alibaba Cloud services in the same region. If your application server is also in the same region, use the internal network endpoint to access the ID Verification service for a more secure and stable connection. 

      • Optimization for overseas access: Network conditions outside the Chinese mainland can be complex. To reduce latency and minimize request failures, optimize your integration by following the best practices in Server-side Network Latency Analysis and Optimization.

      China (Hong Kong)

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

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

    Online debugging and integration

    Note

    Before you debug or integrate, read the Use OpenAPI guide to understand how to call APIs on the OpenAPI platform and how to obtain the SDK.

    You can run this API directly in OpenAPI Explorer to debug and generate SDK code examples.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The solution to use. Valid value:

    eKYC: The eKYC solution. Users complete both document recognition and face liveness verification.

    eKYC

    MerchantBizId

    String

    Yes

    A unique business identifier that you define for troubleshooting purposes. The value can be a combination of up to 32 letters and digits.

    Note

    Alibaba Cloud does not check the uniqueness of this value. To simplify troubleshooting, ensure this value is unique.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    Yes

    The MetaInfo parameter is required when you call the initialization API. If you have not integrated the client software development kit (SDK), you must provide a static value for this parameter. You must accurately specify the deviceType field and leave the other fields unspecified.

    Example code:

    {
  "deviceType": "h5"
}

    deviceType valid values:

    • 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 delivery, log investigation, and security verification. If you provide a static value for MetaInfo, ensure that deviceType matches the actual environment. An incorrect value will cause authentication URL delivery to fail.

    {
  "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 user ID that you customize, or another identifier that can identify a specific user, such as a mobile number or email address. We strongly recommend desensitizing this value (for example, by hashing it).

    123456789

    ReturnUrl

    String

    No

    The redirect URL for your business page.

    Important

    This parameter is optional for iframe-based integrations only

    https://www.alibabacloud.com

    DocType

    String

    Yes

    An 8-digit value that uniquely identifies the document type. For more information, see the table below.

    01000000

    SceneCode

    String

    No

    A custom verification scenario ID that you can use to query related records in the console. The value can be a combination of up to 10 letters, digits, or underscores (_).

    1234567890

    IdSpoof

    String

    No

    Specifies whether to enable anti-spoofing detection for documents:

    • Y: Enables the feature.

    • N: Disables the feature. This is the default value.

    Y

    Authorize

    String

    No

    Specifies whether to enable identity verification against official databases:

    • T: Enables the feature.

    • F: Disables the feature. This is the default value.

    Note

    This feature is currently available only for the Chinese mainland second-generation resident ID card.

    F

    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.

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

    SecurityLevel

    String

    No

    Specifies the security level for the verification process. Valid values:

    • 01: normal mode. This mode is suitable for low-risk scenarios with restricted device information collection.

    • 02 (default): secure mode.

      Note

      • The secure mode uses the face guard module in the SDK to assess device environment security using device information. This enhances protection against injection attacks. We recommend enabling this mode.

      • During development and testing, the face guard module might flag a test device's environment as a risk. This can cause the verification to fail with Subcode 206. To improve testing efficiency, we recommend setting the mode to "01 normal mode". For production, switch to "02 secure mode" to ensure enhanced security.

    02

    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.

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

    IdThreshold

    String

    No

    Sets the mode for the OCR quality check. Valid values are:

    • 1: strict mode

    • 2: loose mode

    • 3 (default): Disables the quality check.

    3

    Model

    String

    No

    Specifies the type of liveness detection to perform. Valid values:

    • SILENT: Silent liveness detection. Currently supported only for Web SDK integration on mobile and PC.

    • LIVENESS : Liveness detection that uses a blinking action (default).

    • PHOTINUS_LIVENESS: Liveness detection that uses a blinking action and a color pattern (not supported on PC).

    Note

    For supported SDK versions, see Client SDK release notes.

    PHOTINUS_LIVENESS

    DocVideo

    String

    No

    Specifies whether to store an evidence video. Valid values:

    • N (default): The evidence video is not stored.

    • Y: Captures a 1- to 2-second evidence video of the user's face during verification. The query operation returns the video.

    Note

    The system may discard large video files during network instability to prioritize the transmission of essential verification images.

    N

    ShowAlbumIcon

    String

    No

    Specifies whether to display the option to upload a photo from an album during document OCR:

    • 1: Displays the entry. This is the default value.

    • 0: Does not display the entry.

    1

    ShowOcrResult

    String

    No

    Specifies whether to display the recognition result page during document OCR:

    • 1: Displays the page. This is the default value.

    • 0: Does not display the page.

    1

    ShowGuidePage

    String

    No

    Specifies whether to display the guide page:

    Note

    This setting is not supported on PCs.

    • 1: Displays the page. This is the default value.

    • 0: Does not display the page.

    1

    ProcedurePriority

    String

    No

    Specifies whether to offer a fallback option if compatibility issues occur during verification on a mobile H5 page.

    • url (default): Fallback is supported. The page displays the verification URL, which the user can copy to another browser to continue the process.

    • keep: Fallback is not supported. The system directly returns the cause of the error and ends the verification process.

    Note

    • This setting is not supported on PCs.

    • If your use case involves completing the verification on a webpage embedded within an application, we recommend setting this parameter to keep to disallow the URL fallback.

    url

    CallbackUrl

    String

    No

    The callback URL for receiving verification results. The callback request uses the GET method by default, and the URL must start with https. After verification completes, the platform invokes this URL and automatically appends the following parameters:

    • transactionId

    • passed

    • subcode

    Warning

    • The service validates this URL for accessibility before processing the API call. If the provided URL is not accessible from the public network, the service returns a 400 error.

    • The callback is triggered immediately after the verification process completes but may be delayed by network conditions. We recommend first handling the completion notification on the client and then calling the query API to retrieve detailed verification results.

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

    CallbackToken

    String

    No

    A security token that you generate for anti-replay and anti-tampering verification.

    If you set this parameter, the CallbackToken field is included in the callback to the CallbackUrl.

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    No

    Specifies whether to enable strict face quality detection:

    Important

    This feature is not supported by the Web SDK.

    • Y: Enables the feature. This is the default value.

    • N: Disables the feature.

    Y

    EditOcrResult

    String

    No

    Specifies whether users can edit information on the OCR result page.

    • 1: Supported. This is the default value.

    • 0: Not supported.

    0

    Document types

    DocType

    Document

    01000000

    Passport

    00000006

    Hong Kong (China) Identity Card (2003 version)

    00000008

    Hong Kong (China) Identity Card (2018 version)

    00000007

    Exit-entry Permit for Travelling to and from Hong Kong and Macao

    00000009

    Mainland Travel Permit for Hong Kong and Macao Residents

    000000011

    Macao (China) Identity Card

    000000012

    Mainland Travel Permit for Taiwan Residents

    00000001

    Chinese mainland second-generation resident ID card

    Returned data

    Parameter

    Type

    Description

    Example

    HTTP status code

    Integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    String

    The request ID.

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

    Code

    String

    Return code: For more information, see Server-side HTTP status codes.

    Success

    Message

    String

    A detailed description of the response code.

    success

    Result.TransactionId

    String

    The unique identifier for the authentication process. This field is used for billing statistics and to call the CheckResult API.

    Important

    • If an error occurs during the request, such as an invalid parameter, TransactionId is not returned.

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

    • You must complete the authentication process within 30 minutes of obtaining the TransactionId or TransactionUrl. After this period, the ID expires and cannot be used for authentication.

    hksb7ba1b28130d24e015d********

    Result.TransactionUrl

    String

    The web verification URL. After the verification is complete, the user is redirected to the ReturnUrl specified in the request parameters.

    Important

    • Do not modify the TransactionUrl during integration. Doing so causes a verification exception.

    • For security, the TransactionUrl is for single use only. Reusing it causes a verification exception.

    • Complete verification within 30 minutes of obtaining the TransactionId or TransactionUrl. Otherwise, they expire.

    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.

    Note

    This parameter is required for H5 web integrations that use an iframe.

    hksb7ba1b28130d24e015d*********