全部产品
Search
文档中心

ID Verification:Initialize

更新时间:Mar 11, 2026

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

接口信息

  • 接口名:Initialize

  • 请求方法:HTTPS POST

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

  • QPS限量:API独享QPS限量,详情请参见ID Verification服务端API QPS限量说明

  • 服务地址:

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

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

    新加坡

    • 公网:cloudauth-intl.ap-southeast-1.aliyuncs.com

    • 内网:cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

    印度尼西亚

    • 公网:cloudauth-intl.ap-southeast-5.aliyuncs.com

    • 内网:cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

    中国香港

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

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

    马来西亚(吉隆坡)

    • 公网:cloudauth-intl.ap-southeast-3.aliyuncs.com

    • 内网:cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

在线调试和集成

说明

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

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

请求参数

名称

类型

是否必选

描述

Example

ProductCode

String

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

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

eKYC_PRO

SceneCode

String

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

1234567890

MerchantBizId

String

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

说明

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

e0c34a77f5ac40a5aa5e6ed20c35****

MetaInfo

String

MetaInfo环境参数,需要通过客户端SDK获取。

请参考对应平台的客户端SDK接入文档,获取MetaInfo。

说明

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

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

证件类型。

您可以在证件类型表中查询支持的证件编码;在证件OCR字段表中查询每种证件的ORC返回字段详情。

重要

受地域模型限制,不同地域支持识别的证件类型不一致。

  • 新加坡地域:支持识别证件类型表中的证件。

  • 印度尼西亚地域:仅支持识别印度尼西亚身份证和全球护照(证件类型编码IDN01001GLB03002)。

  • 马来西亚地域:仅支持识别马来西亚身份证和全球护照(证件类型编码MYS01001GLB03002

GLB03001

SecurityLevel

String

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

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

  • 02:安全模式,相对严格的模式(默认)

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

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

02

IdThreshold

String

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

  • 0:标准模式

  • 1:严格模式

  • 2:宽松模式

  • 3:关闭质量检测(默认)

0

Model

String

要进行活体检测的类型:

  • LIVENESS:眨眼动作活体检测(默认)。

  • PHOTINUS_LIVENESS:眨眼动作活体检测和炫彩活体(PC端不支持)检测。

说明

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

PHOTINUS_LIVENESS

DocVideo

String

是否需要存证视频。

  • N:不需要(默认)。

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

说明

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

N

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字段。

NMjvQanQgplBSaEI0sL********

AppQualityCheck

String

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

  • Y:开启(默认)

  • N:不开启

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

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

N

Pages

String

采集页配置,多页使用,连接。取值范围:

  • 01:证件人像面(默认)

  • 01,02 :证件人像面与背面

    说明

    仅部分证件支持采集多页,具体信息,请参见证件类型表

01

ShowGuidePage

String

是否展示引导页面开关:

  • 1:展示(默认)

  • 0:不展示

1

DocScanMode

String

OCR证件扫描模式:

  • shoot:拍照(默认)

  • scan:扫描

  • auto:拍照/扫描自动切换

shoot

Authorize

String

是否启用权威数据源核验以增强证件防伪能力。仅当IdSpoof参数设置开启时,该参数适用。

  • T:启用

  • F:不启用(默认)

说明
  • 适用证件类型:中国居民身份证(CHN01001)、中国内地驾驶证(CHN02001)、印尼身份证(IDN01001)。对于印尼身份证数据源核验服务,仅当输入卡证类型为IDN01001且调用节点为印尼时才能生效,产品当前处于公测期间,暂不支持直接集成,请联系我们获取体验demo。

  • 数据传输声明:启用此参数,即表示同意将用户的姓名和证件号码传输至中国内地权威数据源或者印尼权威数据源(当输入满足上述描述时)进行一致性校验。

  • 性能影响:启用后,中国居民身份证及中国内地驾驶证接口响应时间将增加约 1-2 秒,印尼身份证接口响应时间将增加10-30秒,建议同步调整超时时间设置。

  • 验证结果

    • Subcode 212:适用于中国居民身份证和中国内地驾驶证接口。当信息核验结果不一致时返回。

    • Subcode 202、207、209、214、215、216、217、218:适用于印尼身份证接口,表示个人信息与提交信息不一致,详细code说明及建议,请参见ResultObject.SubCode错误码说明

T

Mobile

String

传入印度尼西亚电话号码,需校验格式(以+62开头,后接9-11位数字),此字段仅在Authorize=T时生效。

说明

该字段仅在开启印尼数据源时必传。

+6281293671234

e-Mail

String

用户电子邮件地址。此字段仅在Authorize=T时生效。

说明

该字段仅在开启印尼数据源时必传。

a*@gmail.com

返回数据

名称

类型

描述

示例值

HTTP Status Code

Integer

HTTP状态码。

200

HTTP Body

RequestId

String

请求ID。

130A2C10-B9EE-4D84-88E3-5384FF03****

Code

String

返回Code

Success

Message

String

返回Code的详细描述。

success

Result.TransactionId

String

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

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

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

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

hksb7ba1b28130d24e015d6********

Result.Protocol

String

认证标准加密协议。

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

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

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