All Products
Search

This Product

    ID Verification:Initialize

    Document Center

    ID Verification:Initialize

    Last Updated:Nov 26, 2024

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

    Initiate a verification request

    Operation name: Initialize.

    Endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com.

    Request method: HTTPS POST.

    Operation description: Before you start an eKYC process, you must call this operation to obtain a transaction ID for different operations that are involved in the eKYC process.

    QPS limits: Limits are imposed on the queries per second (QPS) of APIs. For more information, see QPS limits of ID Verification - KYC server-side APIs.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The solution that you want to use. Valid value:

    eKYC, which specifies the eKYC solution. If you use the eKYC solution, document recognition and face liveness verification are required for your customer.

    eKYC

    SceneCode

    String

    No

    The ID of your custom verification scenario. You can enter the ID in the ID Verification console to query related records. You can specify a custom value that is 10 characters in length and contains letters, digits, and underscores (_).

    1234567890

    MerchantBizId

    String

    Yes

    The unique identifier of your business, which is used for troubleshooting. You can specify a custom value that is 32 characters in length and contains letters and digits. Make sure that the value is unique.

    Note

    ID Verification does not check the uniqueness of the value. For tracing purposes, we recommend that you specify a unique value.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    Yes

    The environment parameters, which are obtained by using a client SDK. For more information, see Integration by using the Web SDK mode.

    Note

    Specify the obtained parameters as environment parameters. You do not need to modify the parameters.

    {"zimVer":"3.0.0","appVersion": "1","bioMetaInfo": "4.1.0:1150****,0","appName": "com.aliyun.antcloudauth","deviceType": "h5","osVersion": "iOS 10.3.2","apdidToken": "","deviceModel": "iPhone9,1"}

    MerchantUserId

    String

    Yes

    The ID of a customer. You can specify a custom value, such as a mobile phone number or an email address. Before you specify a value, we recommend that you perform data masking. For example, you can perform hashing.

    123456789

    IdSpoof

    String

    No

    Specifies whether to enable anti-counterfeiting detection on documents. Valid values:

    • Y

    • N (default)

    Y

    DocType

    String

    Yes

    The document type. You can specify an 8-digit value to uniquely identify a document type. For more information, see the "Document types" section of this topic.

    01000000

    Authorize

    String

    No

    Specifies whether to enable data verification against official data sources. Valid values:

    • T

    • F (default)

    Note

    Data verification against official data sources supports only second-generation ID cards for residents in the Chinese mainland.

    F

    SecurityLevel

    String

    No

    The mode for the different security levels of the verification process. Valid values:

    • 01: the normal mode. This mode is applicable only to low-risk scenarios in which limits are imposed on device information collection.

    • 02 (default): the secure mode, which is a strict mode.

      Note

      The secure mode allows you to use the face guard module added to the ID Verification SDK to check the security of the device that is used to collect face information based on the device information. This helps intercept injection attacks. We recommend that you select this mode.

    02

    IdThreshold

    String

    No

    The threshold mode for the quality check of OCR. Valid values:

    • 0: the default mode.

    • 1: the strict mode.

    • 2: the loose mode.

    • 3: disables quality check.

    0

    Model

    String

    No

    The type of liveness detection that you want to perform. Valid values:

    • LIVENESS (default): blink-based detection.

    • PHOTINUS_LIVENESS (recommended): blink-based plus color-based liveness detection.

    • PHOTINUS_FAR_NEAR_LIVENESS: blink-based, near and far distance-based, plus color-based liveness detection.

    Note

    • For more information about the SDK versions that can be integrated, see SDK release notes.

    • Blink-based plus color-based liveness detection is not supported on PCs.

    PHOTINUS_LIVENESS

    DocVideo

    String

    No

    Specifies whether to store the evidence video. Valid values:

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

    • Y: During the verification process, the video of the face verification process that lasts 1 to 2 seconds is collected and returned from the query operation.

    Note

    • The system discards the video file when the network is unstable because the size of the video file is large. This ensures the stable transmission of images required for the verification.

    • Videos cannot be returned from PCs.

    N

    Document types

    DocType

    Document

    01000000

    Passports (global)

    00000006

    ID cards (Hong Kong (China)) (2003 version)

    00000008

    ID cards (Hong Kong (China)) (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

    ID cards (Macao (China))

    000000012

    Mainland Travel Permit for Taiwan Residents

    00000001

    Chinese mainland second generation identity card

    Response parameters

    Parameter

    Type

    Description

    Example

    HTTP Status Code

    Integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    String

    The request ID.

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

    Code

    String

    The code that is returned for the request. For more information, see HTTP status codes and messages.

    success

    Message

    String

    The message that is returned for the request.

    success

    Result.TransactionId

    String

    The unique identifier of the verification process. This parameter is used for billing. This parameter is also used to call the CheckResult operation.

    Note

    If an error occurred in the request, Result.TransactionId is not returned. For example, a parameter is invalid.

    hksb7ba1b28130d24e015d694361bee4

    Codes and message descriptions

    HTTP status code

    Code

    Message description

    200

    Success

    The request is successful.

    400

    MissingParameter

    A required parameter is empty.

    400

    InvalidParameter

    A parameter is set to an invalid value.

    403

    Forbidden.RAMUserAccessDenied

    The RAM user is not granted the required permission AliyunAntCloudAuthFullAccess. For more information, see Authorize a RAM user to access ID Verification - KYC.

    403

    Forbidden.AccountAccessDenied

    The account has overdue payments. We recommend that you add funds to the account and try again.

    403

    Throttling.Api

    API throttling is triggered.

    404

    ProcessNotCompleted

    The verification process is not complete.

    500

    InternalError

    An internal error occurred. To troubleshoot the error, we recommend that you submit your feedback to engineers.