All Products
Search

This Product

    ID Verification:InitializeV2

    Document Center

    ID Verification:InitializeV2

    Last Updated:Oct 27, 2026

    Starts an ID_NFC verification session and returns a transactionId for subsequent API calls

    Initiate a verification request

    • API operation: InitializeV2

    • Request method: HTTPS POST

    • Description: After the client obtains MetaInfo, call this operation to get a transactionId. The client uses this ID to initiate authentication.

      Important

      Each transactionId is for single use only. The ID expires immediately after an authentication attempt, regardless of the outcome (success, failure, or cancellation). Do not reuse the ID to call the SDK. To re-authenticate, you need to request a new transactionId from the server-side.

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

    • Service 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

      Asia Pacific SE 5 (Jakarta)

      • 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.

    You can run this operation in OpenAPI Explorer for testing, and generate SDK code examples for this operation at SDK code examples.

    Request parameters

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The verification solution to use.

    Set to ID_NFC.

    ID_NFC

    SceneCode

    String

    No

    A custom scenario ID for querying related records in the console.

    Must be a 10-character string containing only letters, digits, and underscores.

    1234567890

    MerchantBizId

    String

    Yes

    A unique business identifier for troubleshooting. Must be a 32-character alphanumeric string.

    Note

    Alibaba Cloud does not enforce uniqueness. Ensure uniqueness on your side for effective tracking.

    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.

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

    No

    A custom user identifier, such as a phone number or email address. Pre-desensitize this value (for example, by hashing) before passing it.

    123456789

    DocType

    String

    Yes

    Document type as an 8-digit code. Only global passports are supported. Set to `01000000`.

    01000000

    MRTDInput

    String

    Yes

    Input source for MRTD verification parameters. NFC uses this value to decrypt the certificate chip data.

    • 0: User input

    • 1: OCR reading

    • 2: API operation input

    0

    DocumentNumber

    String

    No

    Document number.

    Required when `MRTDInput` = 2.

    DateOfBirth

    String

    No

    Date of birth on the certificate.

    Required when `MRTDInput` = 2.

    DateOfExpiry

    String

    No

    Expiry date on the certificate.

    Required when `MRTDInput` = 2.

    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 security token you generate for anti-replay and tamper-proofing.

    When set, the `CallbackToken` field is included in the `CallbackUrl` callback.

    NMjvQanQgplBSaEI0sL86******

    ShowGuidePage

    String

    No

    UI configuration: Show guide page:

    • 1: Show (default)

    • 0: Do not show

    Supported in Native SDK version 1.4.0 and above.

    1

    Returned data

    Name

    Type

    Description

    Example

    HTTP Status Code

    Integer

    HTTP status code

    200

    HTTP Body

    RequestId

    String

    Request ID

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

    Code

    String

    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.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*********