全部产品
Search

搜索本产品

    ID Verification：InitializeV2

    文档中心

    ID Verification：InitializeV2

    更新时间：Sep 03, 2026

    InitializeV2接口是服务端发起认证的起始接口，本文介绍InitializeV2接口的输入和输出参数。

    发起认证请求

    • 接口名：InitializeV2

    • 请求方法：HTTPS POST

    • 接口说明：客户端获取MetaInfo后，开始认证流程前，通过本接口获取transactionId，客户端使用获取的transactionId发起认证。

    • QPS限量：API独享QPS限量，详情请参见服务端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接口在OpenAPI平台的调用方式和SDK及其代码的获取方式。

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

    请求参数

    名称

    类型

    是否必选

    描述

    示例

    ProductCode

    String

    是

    要接入的产品方案。

    固定取值：ID_NFC。

    ID_NFC

    SceneCode

    String

    否

    您自定义的认证场景ID，用于后续控制台输入此场景ID查询相关记录。

    支持长度为10位的字母、数字和下划线的组合。

    1234567890

    MerchantBizId

    String

    是

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

    说明

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

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    是

    客户端环境信息。建议由对应 SDK 生成；若自行构造，至少须正确传入 deviceType。

    示例代码：

    {
  "deviceType": "h5"
}

    deviceType 取值说明：

    • Android 原生 App：android

    • iOS 原生 App：ios

    • H5 内嵌页面：h5

    • PC 浏览器网页：web

    重要

    建议通过认证 SDK 获取 MetaInfo，以获取更准确、详细的客户端信息，从而支持认证 URL 下发、日志排查及安全校验等场景。若自行构造 MetaInfo 固定值，请务必确保 deviceType 与实际接入环境一致，填写错误将导致认证 URL 下发异常。

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

    DocType

    String

    是

    证件类型，以8位数字组合作为唯一标识。目前仅支持全球护照，取值：01000000。

    01000000

    MRTDInput

    String

    是

    MRTD校验参数输入来源。NFC读取证件芯片信息时依赖该参数解密信息。

    • 0：用户输入

    • 1：OCR读取

    • 2：接口传入

    0

    DocumentNumber

    String

    否

    证件号

    MRTDInput = 2时，必传。

    DateOfBirth

    String

    否

    证件上的出生日期

    MRTDInput = 2时，必传。

    DateOfExpiry

    String

    否

    证件上的过期时间

    MRTDInput = 2时，必传。

    CallbackUrl

    String

    否

    认证结果回调地址，必须以 https 开头。平台通过 GET 回调并追加 transactionId、passed、subcode。

    若此地址公网不可访问，则会返回 400 报错。

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

    CallbackToken

    String

    否

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

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

    NMjvQanQgplBSaEI0sL86******

    ShowGuidePage

    String

    否

    【UI配置】是否展示引导页：

    • 1：展示（默认）

    • 0：不展示

    Native SDK 1.4.0及以上版本支持。

    1

    返回参数

    名称

    类型

    描述

    示例

    HTTP Status Code

    Integer

    HTTP状态码

    200

    HTTP Body

    RequestId

    String

    请求ID

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

    Code

    String

    返回Code，具体信息请参见服务端返回HTTP状态码说明。

    Success

    Message

    String

    返回Code的详细描述。

    success

    Result.TransactionId

    String

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

    重要

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

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

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

    hksb7ba1b28130d24e015d6********

    Result.Protocol

    String

    认证标准加密协议。

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

    hksb7ba1b28130d24e015d*********