全部產品
Search

搜尋本產品

    ID Verification：Initialize

    文件中心

    ID Verification：Initialize

    更新時間：Jan 31, 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：strict 模式

    • 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

    服務不可用，請反饋工程師排查。