全部产品
Search

搜索本产品

    ID Verification：Initialize

    文档中心

    ID Verification：Initialize

    更新时间：Nov 20, 2024

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

    发起认证请求

    接口名：Initialize。

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

    请求方法：HTTPS POST。

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

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

    请求参数

    名称

    类型

    是否必选

    描述

    Example

    ProductCode

    String

    是

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

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

    eKYC

    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

    ReturnUrl

    String

    是

    业务页面回跳的目标地址。

    https://www.alibabacloud.com

    DocType

    String

    是

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

    01000000

    SceneCode

    String

    否

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

    1234567890

    IdSpoof

    String

    否

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

    • Y：开启

    • N：关闭（默认）

    Y

    Authorize

    String

    否

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

    • T：开启

    • F：关闭（默认）

    说明

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

    F

    LanguageConfig

    String

    否

    自定义语言配置。根据配置模板，将需新增的语言配置转换为JSON字符串后，通过该接口传入实现自定义配置。更多详情，请参见新增语言。

    说明

    目前仅适用于websdk接入模式，PC模式暂不支持。

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

    SecurityLevel

    String

    否

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

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

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

      说明

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

    02

    StyleConfig

    String

    否

    自定义UI配置。根据配置模板，将您自定义的UI配置转换为JSON字符串后，通过该接口传入实现。更多信息，请参见IDV KYC UI样式自定义。

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

    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

    ShowBlbumIcon

    String

    否

    证件OCR识别环节，是否展示相册上传入口：

    说明

    PC端不支持此开关。

    • 1：展示（默认）

    • 0：不展示

    1

    ShowOcrResult

    String

    否

    证件OCR识别环节，是否展示识别结果页：

    说明

    PC端不支持此开关。

    • 1：展示（默认）

    • 0：不展示

    1

    ShowGuidePage

    String

    否

    是否展示引导页面开关：

    说明

    PC端不支持此开关。

    • 1：展示（默认）

    • 0：不展示

    1

    ProcedurePriority

    String

    否

    当移动端H5方式认证出现兼容性问题时，是否允许展示降级的处理方式。

    • url（默认）：支持降级。页面展示认证URL，用户可复制URL打开或者切换浏览器继续认证。

    • keep：不支持降级。直接返回错误原因，并结束认证流程。

    说明

    • PC端不支持此开关。

    • 若业务应用场景为App内嵌网页完成认证，建议此参数设置为keep，不允许降级URL。

    url

    证件类型列表

    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

    Result.TransactionUrl

    String

    Web认证URL，认证结束后根据入参ReturnUrl进行跳转。

    重要

    • 集成过程中，不要对TransactionUrl做任何操作或修改，否则会导致认证异常。

    • 为保障认证过程安全有效，TransactionUrl仅能使用一次，重复访问也将导致认证异常。

    https://www.alibabacloud.com/index.html?clientcfg=****

    返回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

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