全部产品
Search

搜索本产品

    ID Verification：Initialize

    文档中心

    ID Verification：Initialize

    更新时间：Dec 16, 2024

    本文介绍如何通过调用Initialize接口发起eKYC请求。

    发起认证请求

    接口名：Initialize。

    服务地址：cloudauth-intl.cn-hongkong.aliyuncs.com。

    请求方法：HTTPS POST。

    接口说明：每次开始eKYC认证流程前, 通过本接口获取transactionId，用来串联认证请求中的各个接口。

    QPS限量：API独享QPS限量，详情请参见ID Verification - KYC 服务端API QPS限量说明。

    请求参数

    名称

    类型

    是否必选

    描述

    Example

    ProductCode

    String

    是

    要接入的产品方案。取值：

    eKYC：使用eKYC产品方案，您的用户需要完成证件识别和活体认证整个流程。

    eKYC

    SceneCode

    String

    否

    您自定义的认证场景ID，用于后续控制台输入此场景ID查询相关记录使用。支持长度为10位的字母、数字或下划线的组合。

    1234567890

    MerchantBizId

    String

    是

    您自定义的业务唯一标识，用于后续定位排查问题使用。支持长度为32位的字母和数字的组合，请确保唯一。

    说明

    阿里云服务器不会对该字段的值进行唯一性检查。为了更好的跟踪，强烈建议保证字段唯一性。

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    是

    MetaInfo环境参数，需要通过客户端SDK获取。更多信息，请参见PC或移动端H5网页接入。

    说明

    无须修改返回值，直接透传即可。

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

    是

    您自定义的用户ID，或者其他可以识别特定用户的标识，例如手机号码、邮箱地址等。强烈建议对该字段的值进行预先脱敏，例如对值进行哈希处理。

    123456789

    IdSpoof

    String

    否

    是否开启证件防伪检测功能：

    • Y：开启。

    • N：关闭（默认）。

    Y

    DocType

    String

    是

    证件类型，以8位数字组合作为唯一标识，详见下表。

    01000000

    Authorize

    String

    否

    是否开启官方数据库身份核验：

    • T：开启。

    • F：关闭（默认）。

    说明

    目前仅适用于中国内地第二代居民身份证。

    F

    SecurityLevel

    String

    否

    代表认证流程不同安全水位的模式，可选值：

    • 01：普通模式，仅适用低风险且对设备信息采集限制的场景。

    • 02：安全模式，相对严格的模式（默认）。

      说明

      安全模式指通过SDK新增的人脸保镖模块通过设备信息识别刷脸环境设备的安全性，有效增强注入攻击的拦截。强烈建议您选择。

    02

    IdThreshold

    String

    否

    自定义OCR质量检测阈值模式：

    • 0：系统默认

    • 1：严格模式

    • 2：宽松模式

    • 3（默认）：关闭质量检测

    0

    Model

    String

    否

    要进行活体检测的类型：

    • LIVENESS（默认）：眨眼动作活体检测。

    • PHOTINUS_LIVENESS（推荐）：眨眼动作活体+炫彩活体双重检测。

    • PHOTINUS_FAR_NEAR_LIVENESS: 眨眼动作+远近+炫彩活体检测。

    说明

    • 支持集成的SDK版本，请参见SDK发布记录。

    • PC端不支持炫彩活体双重检测。

    PHOTINUS_LIVENESS

    DocVideo

    String

    否

    是否需要存证视频。

    • N：不需要（默认）。

    • Y：认证过程中会同时采集用户的刷脸过程视频（1~2s视频文件），并通过查询接口返回。

    说明

    • 因为视频文件较大，当网络不稳定时系统会丢弃视频文件，优先保障认证必要图片传输。

    • PC端不支持返回视频。

    N

    CallbackUrl

    String

    否

    认证结果的回调通知地址，回调请求方式默认为GET，回调地址必须以https开头。平台在完成认证后会回调该地址，并自动添加以下字段：

    • transactionId

    • passed

    • code

    • subcode

    警告

    此值的传入会在调用接口前做可访问校验，如果传入的地址不能在公网访问，会返回400。

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

    CallbackToken

    String

    否

    安全Token，由您自行生成，用于防重复、防篡改校验。

    如果设置了此值，将会在CallbackUrl回调时携带CallbackToken字段。

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    否

    是否开启人脸严格质量检测。

    • Y：开启（默认）

    • N：不开启

    重要

    • 此配置需要客户端SDK的支持，如果设置开启，但客户端SDK没有集成人脸质量检测模块，则此配置视同不开启。

    • 客户端SDK版本需要1.2.5及以上版本。

    N

    证件类型列表

    DocType

    对应证件

    01000000

    全球护照

    00000006

    香港居民身份证（2003版）

    00000008

    香港居民身份证（2018版）

    00000007

    往来港澳通行证

    00000009

    港澳居民来往内地通行证

    000000011

    澳门身份证

    000000012

    台湾居民来往大陆通行证

    00000001

    中国内地第二代居民身份证

    返回数据

    名称

    类型

    描述

    示例值

    HTTP Status Code

    Integer

    HTTP状态码。

    200

    HTTP Body

    RequestId

    String

    请求ID。

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

    Code

    String

    返回码。关于返回码的具体信息，请参见返回Code和Message说明。

    success

    Message

    String

    请求消息的响应信息。

    success

    Result.TransactionId

    String

    整个认证流程的唯一标识。该字段为计费统计字段，并用于发起CheckResult接口请求。

    说明

    当请求过程中出现错误时，例如参数无效，则不会返回transactionId。

    hksb7ba1b28130d24e015d694361bee4

    返回Code和Message说明

    HTTP状态码

    Code

    Message说明

    200

    Success

    请求成功。

    400

    MissingParameter

    参数不能为空。

    400

    InvalidParameter

    非法参数。

    403

    Forbidden.RAMUserAccessDenied

    需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。更多信息，请参见授权RAM用户访问服务。

    403

    Forbidden.AccountAccessDenied

    账户存在欠费，请充值后再进行操作。

    403

    Throttling.Api

    API限流拦截。

    404

    ProcessNotCompleted

    整个认证流程未完成。

    500

    InternalError

    系统内部错误，请反馈工程师排查。