全部產品
Search

搜尋本產品

    ID Verification：Initialize

    文件中心

    ID Verification：Initialize

    更新時間：Dec 07, 2024

    本文介紹如何通過調用Initialize介面發起eKYC請求。

    發起認證請求

    介面名：Initialize。

    服務地址：cloudauth-intl.cn-hongkong.aliyuncs.com。

    要求方法：HTTPS POST。

    介面說明：每次開始eKYC認證流程前, 通過本介面擷取transactionId和transactionUrl，用來串聯認證請求中的各個介面。

    QPS限量：API獨享QPS限量，詳情請參見ID Verification - KYC 服務端API QPS限量說明。

    請求參數

    名稱

    類型

    是否必選

    描述

    Example

    ProductCode

    String

    是

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

    eKYC：使用eKYC產品方案，您的使用者需要完成證件識別和活體認證整個流程。

    eKYC

    MerchantBizId

    String

    是

    您自訂的業務唯一標識，用於後續定位排查問題使用。支援長度為32位的字母和數位組合，請確保唯一。

    說明

    阿里雲伺服器不會對該欄位的值進行唯一性檢查。為了更好的跟蹤，強烈建議保證欄位唯一性。

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    是

    MetaInfo環境參數，需要通過用戶端SDK擷取。更多資訊，請參見PC或移動端H5網頁接入。

    說明

    無須修改傳回值，直接透傳即可。

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

    ReturnUrl

    String

    是

    業務頁面回跳的目標地址。

    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字串後，通過該介面傳入實現自訂配置。更多詳情，請參見新增語言。

    說明

    目前僅適用於websdk接入模式，PC模式暫不支援。

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

    SecurityLevel

    String

    否

    代表認證流程不同安全水位的模式，可選值：

    • 01：普通模式，僅適用低風險且對裝置資訊採集限制的情境。

    • 02：安全模式，相對嚴格的模式（預設）。

      說明

      安全模式指通過SDK新增的人臉保鏢模組通過裝置資訊識別刷臉環境裝置的安全性，有效增強注入攻擊的攔截。強烈建議您選擇。

    02

    StyleConfig

    String

    否

    自訂UI配置。根據配置模板，將您自訂的UI配置轉換為JSON字串後，通過該介面傳入實現。更多資訊，請參見IDV KYC UI樣式自訂。

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

    IdThreshold

    String

    否

    自訂OCR品質檢測閾值模式：

    • 0：系統預設

    • 1：strict 模式

    • 2：寬鬆模式

    • 3（預設）：關閉品質檢測

    0

    Model

    String

    否

    要進行活體檢測的類型：

    • LIVENESS（預設）：眨眼動作活體檢測。

    • PHOTINUS_LIVENESS（推薦）：眨眼動作活體+炫彩活體雙重檢測。

    • PHOTINUS_FAR_NEAR_LIVENESS: 眨眼動作+遠近+炫彩活體檢測。

    說明

    • 支援整合的SDK版本，請參見SDK發布記錄。

    • PC端不支援炫彩活體雙重檢測。

    PHOTINUS_LIVENESS

    DocVideo

    String

    否

    是否需要存證視頻。

    • N：不需要（預設）。

    • Y：認證過程中會同時採集使用者的刷臉過程視頻（1~2s視頻檔案），並通過查詢介面返回。

    說明

    • 因為視頻檔案較大，當網路不穩定時系統會丟棄視頻檔案，優先保障認證必要圖片傳輸。

    • PC端不支援返回視頻。

    N

    ShowBlbumIcon

    String

    否

    證件OCR識別環節，是否展示相簿上傳入口：

    說明

    PC端不支援此開關。

    • 1：展示（預設）

    • 0：不展示

    1

    ShowOcrResult

    String

    否

    證件OCR識別環節，是否展示識別結果頁：

    說明

    PC端不支援此開關。

    • 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

    • code

    • subcode

    警告

    此值的傳入會在調用介面前做可訪問校正，如果傳入的地址不能在公網訪問，會返回400。

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

    CallbackToken

    String

    否

    安全Token，由您自行產生，用於防重複、防篡改校正。

    如果設定了此值，將會在CallbackUrl回調時攜帶CallbackToken欄位。

    NMjvQanQgplBSaEI0sL86WnQplB

    證件類型列表

    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-5384FF039795

    Code

    String

    返回碼：關於返回碼的具體資訊，請參見返回Code和Message說明。

    success

    Message

    String

    請求訊息的響應資訊。

    success

    Result.TransactionId

    String

    整個認證流程的唯一標識。該欄位為計費統計字段，並用於發起CheckResult介面請求。

    說明

    當請求過程中出現錯誤時，例如參數無效，則不會返回transactionId。

    hksb7ba1b28130d24e015d694361bee4

    Result.TransactionUrl

    String

    Web認證URL，認證結束後根據入參ReturnUrl進行跳轉。

    重要

    • 整合過程中，不要對TransactionUrl做任何操作或修改，否則會導致認證異常。

    • 為保障認證過程安全有效，TransactionUrl僅能使用一次，重複訪問也將導致認證異常。

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

    返回Code和Message說明

    HTTP狀態代碼

    Code

    Message說明

    200

    Success

    請求成功。

    400

    MissingParameter

    參數不可為空。

    400

    InvalidParameter

    非法參數。

    403

    Forbidden.RAMUserAccessDenied

    需要給RAM使用者授予AliyunAntCloudAuthFullAccess的操作許可權。更多資訊，請參見授權RAM使用者訪問服務。

    403

    Forbidden.AccountAccessDenied

    賬戶存在欠費，請儲值後再進行操作。

    403

    Throttling.Api

    API限流攔截。

    404

    ProcessNotCompleted

    整個認證流程未完成。

    500

    InternalError

    系統內部錯誤，請反饋工程師排查。