All Products
Search

This Product

    :Initialize

    Document Center

    :Initialize

    Last Updated:May 22, 2024

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

    Initiate an eKYC 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.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The solution that you want to use. Set the value to KYC_GLOBAL, which specifies the eKYC solution. If you use the eKYC solution, document recognition and face liveness verification are required for your customer.

    KYC_GLOBAL

    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.

    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 SDK integration.

    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": "ios","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

    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.

    01560000

    DocScanMode

    String

    No

    The mode in which the photo of a document is collected. Valid values:

    • manual

    manual

    ProductFlow

    String

    No

    The sequence of document recognition and face liveness verification. Valid values:

    • DOC_FACE (default)

    • FACE_DOC

    DOC_FACE

    CallbackUrl

    String

    No

    The callback notification address for the authentication result. The callback request method defaults to GET, and the callback address must start withhttps. After completing authentication, the platform will call back the address and automatically addtransactionId,passed andsubCode.

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

    CallbackToken

    String

    No

    Security Token for anti duplication and anti-tamper.

    If this value is set, the CallbackToken field will be displayed at the callback address.

    NMjvQanQgplBSaEI0sL86WnQplB

    Document types

    You can click Supported document types in common countries and regions and Supported document types in other countries and regions to download the lists of supported document types in different countries and regions.

    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.

    200

    Message

    String

    The message that is returned for the request.

    Success

    Result.TransactionId

    String

    The unique identifier of the eKYC 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, such as an invalid parameter, Result.TransactionId is not returned.

    hksb7ba1b28130d24e015d694361bee4

    HTTP status codes and messages

    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.

    401

    OcrFail

    The document is unreadable.

    403

    Forbidden.RAMUserAccessDenied

    The RAM user is not granted the required permission AliyunAntCloudAuthFullAccess.

    403

    Forbidden.AccountAccessDenied

    The account has overdue payments. We recommend that you top up your account and try again.

    403

    Throttling.Api

    API throttling is triggered.

    424

    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.