全部产品
Search
文档中心

ID Verification:Initialize

更新时间:Nov 18, 2025

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

发起认证请求

  • 接口名:Initialize

  • 请求方法:HTTPS POST

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

  • 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

SceneCode

String

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

1234567890

MerchantBizId

String

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

说明

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

e0c34a77f5ac40a5aa5e6ed20c35****

MetaInfo

String

MetaInfo环境参数,需要通过客户端SDK获取。更多信息,请参见对应的客户端集成说明。

说明

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

{
  "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:眨眼动作活体+炫彩活体双重检测。

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

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

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

NMjvQanQgplBSaEI0sL86WnQplB

AppQualityCheck

String

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

  • Y:开启(默认)

  • N:不开启

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

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

N

DocPageConfig

String

JSON字符串数组格式:

OCR_ID_BACK: 采集反面页面

说明

当前仅支持中国内地身份证类型

OCR_ID_BACK

ShowGuidePage

String

是否展示引导页面开关:

  • 1(默认):展示

  • 0:不展示

1

DocScanMode

String

OCR证件扫描模式:

  • shoot(默认):拍照

  • scan:扫描

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

shoot

证件类型列表

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

Code

String

返回Code

Success

Message

String

返回Code的详细描述。

success

Result.TransactionId

String

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

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

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

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

hksb7ba1b28130d24e015d6********

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

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