全部产品
Search

搜索本产品

    ID Verification：Initialize

    文档中心

    ID Verification：Initialize

    更新时间：Jan 30, 2026

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

    发起认证请求

    • 接口名：Initialize

    • 请求方法：HTTPS POST

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

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

    • 服务地址：

      说明

      • 内网访问优势：内网指阿里云同一地域内各产品间的私有通信网络。若您的业务服务器部署于阿里云对应地域，请使用内网域名访问 ID Verification 服务，以获得更安全、稳定的通信质量。 

      • 海外访问优化建议：海外网络环境复杂，建议参考服务端网络耗时分析与优化，优化集成方案，降低网络延迟及请求失败概率。

      中国香港

      • 公网：cloudauth-intl.cn-hongkong.aliyuncs.com

      • 内网：cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

    在线调试和集成

    说明

    在调试和集成前，请确保您已完整阅读使用OpenAPI调试和集成服务端API文档，充分了解API接口在OpenAPI平台的调用方式和SDK及其代码的获取方式。

    您可以在OpenAPI Explorer中直接运行本接口进行调试，并生成本接口的SDK代码示例。

    请求参数

    名称

    类型

    是否必选

    描述

    Example

    ProductCode

    String

    是

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

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

    eKYC

    MerchantBizId

    String

    是

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

    说明

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

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    是

    MetaInfo环境参数，实际环境需要通过JS文件，调用函数getMetaInfo()获取，请参考对应平台的客户端接入文档，获取MetaInfo。

    重要

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

    • 服务端基于该参数识别Mobile或PC运行环境，下发不同的认证URL，请参考函数说明真实运行获取。

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

    是

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

    123456789

    ReturnUrl

    String

    否

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

    重要

    仅当使用iframe内嵌方式封装时，此参数非必填。

    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字符串后，通过该接口传入实现自定义配置。更多详情，请参见Web SDK 自定义语种。

    		 

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

    SecurityLevel

    String

    否

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

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

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

      说明

      • 安全模式通过 SDK 新增的设备助手模块，基于设备信息识别刷脸环境的安全性，有效提升对注入攻击的拦截能力。建议启用此模式。

      • 在开发测试阶段，测试设备的环境特征可能导致设备安全助手判定存在风险，从而触发认证失败（Subcode 206）。建议在测试期间将模式手动设置为“01 普通模式”，以提升测试效率；正式上线时切换为“02 安全模式”，以增强认证安全性。

    02

    StyleConfig

    String

    否

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

    		 

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

    IdThreshold

    String

    否

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

    • 0：标准模式

    • 1：严格模式

    • 2：宽松模式

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

    0

    Model

    String

    否

    要进行活体检测的类型：

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

    • PHOTINUS_LIVENESS：眨眼动作活体检测和炫彩活体（PC端不支持）检测。

    • SILENT：静默活体检测。当前仅支持（Mobile / PC）集成方式。

    说明

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

    PHOTINUS_LIVENESS

    DocVideo

    String

    否

    是否需要存证视频。

    • N：不需要（默认）。

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

    说明

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

    N

    ShowBlbumIcon

    String

    否

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

    • 1：展示（默认）

    • 0：不展示

    1

    ShowOcrResult

    String

    否

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

    • 1：展示（默认）

    • 0：不展示

    1

    ShowGuidePage

    String

    否

    是否展示引导页面开关：

    说明

    PC端不支持此开关。

    • 1：展示（默认）

    • 0：不展示

    1

    ProcedurePriority

    String

    否

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

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

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

    说明

    • PC端不支持此开关。

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

    url

    CallbackUrl

    String

    否

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

    • transactionId

    • passed

    • subcode

    警告

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

    • 回调会在认证完成后立即执行，但可能会因为网络等原因延迟，建议您优先接收客户端侧的认证完成通知，再请求查询接口获取认证详情。

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

    CallbackToken

    String

    否

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

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

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    否

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

    重要

    该功能Web SDK暂不支持。

    • Y：开启（默认）

    • N：不开启

    Y

    EditOcrResult

    String

    否

    OCR识别结果页面是否允许用户编辑信息。

    • 1：支持

    • 0：不支持（默认）

    0

    证件类型列表

    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-5384FF0****

    Code

    String

    返回Code。

    Success

    Message

    String

    返回Code的详细描述。

    success

    Result.TransactionId

    String

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

    重要

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

    • 建议将TransactionId与您本次业务流程的业务ID绑定并存储在服务端，在CheckResult时从您服务端存储提取该认证ID，发起结果查询。

    • 获取TransectionId或TransactionUrl成功后，需要在30分钟内完成认证，超过时间将自动失效无法再认证。

    hksb7ba1b28130d24e015d6********

    Result.TransactionUrl

    String

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

    重要

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

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

    • 获取TransectionId或TransactionUrl成功后，需要在30分钟内完成认证，超过时间将自动失效无法再认证。

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

    Result.Protocol

    String

    认证标准加密协议。

    建议获取该参数并传递给客户端 SDK。客户端 SDK 将基于此参数减少网络交互，并支持动态网络切换，以提升用户体验。

    说明

    H5网页接入，选择iframe内嵌集成时依赖该字段。

    hksb7ba1b28130d24e015d*********

    返回Code

    HTTP状态码

    Code

    Message描述

    200

    Success

    请求成功。

    400

    MissingParameter

    参数不能为空。

    InvalidParameter

    非法参数。

    401

    Forbidden.ExceptionRepeatedInvoke

    异常重复调用次数超限。

    403

    Forbidden.RAMUserAccessDenied

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

    Forbidden.AccountAccessDenied

    确保您开通了ID verifycation，并且保证账户未欠费。

    Throttling.Api

    API限流拦截。

    500

    InternalError

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

    503

    ServiceUnavailable

    服务不可用，请反馈工程师排查。