說明：該介面不支援重複調用，即不符合等冪性。

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

bizId

String

32

是

-

業務ID，業務的唯一標識，用於追蹤業務。例如，商戶業務相關資料庫中的序號。

說明：ZOLOZ伺服器不檢查該欄位的值是否唯一。為了更便捷地追蹤業務，建議開啟商戶伺服器，並確保業務ID的唯一性。

"2017839040588699"

metaInfo

String

512

是

-

SDK和使用者裝置的元資訊。該欄位的值由ZOLOZ SDK以JSON字串格式返回。

說明：不要修改傳回值，直接傳遞即可。如果是H5接入模式，則設定為MOB_H5。

"{ \"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }"

userId

String

32

是

-

商戶的使用者ID或其他可用於識別某一使用者的標識，例如手機號碼、電子郵件地址等。

建議對userId欄位的值進行預脫敏，例如進行雜湊處理。

"123456abcd"

docType

String

16

是

-

指定證件類型。例如要上傳的證件是護照，該欄位的值需要設定為00000001003。

ID Recognition支援的證件類型，請參見Real ID和ID Recognition支援的證件類型和返回的OCR結果。

"08520000001"

autoDocTypes

List<String>

200

否

null

證件類型列表。docType和autoDocTypes不能同時傳入，需選擇其中一個傳入。

• 如果傳入autoDocTypes，ZOLOZ將自動對上傳的證件進行分類。

  說明：

• 目前護照不支援自動分類。

• 新加坡證件00650000001和00650000002將統一歸類為00650000001。

• 如果ZOLOZ無法對上傳的證件進行分類或分類的證件類型不在autoDocTypes中，則checkresultAPI將返回NO_REQUIRED_ID。

支援的證件類型，請參見Real ID和ID Recognition支援的證件類型和返回的OCR結果。

["08520000001","08520000002"]

pages

String

32

否

證件類型支援的所有頁

待進行證件識別的證件頁面，多個頁面以英文逗號分隔。例如：

• 1：表示識別第一頁。

• 1,2：表示識別第一頁和第二頁。

有關證件頁面的範圍，請參見Real ID和ID Recognition支援的證件類型和返回的OCR結果。

說明：如果不傳該欄位，預設值為對應證件類型支援的所有頁。

"1"

serviceLevel

String

32

否

IDRECOGNITION0002

服務等級。取值如下：

• IDRECOGNITION0002：基礎防偽等級。

• IDRECOGNITION0003：使用閃光互動模式的高階防偽等級。該等級僅支援在原生SDK模式下使用。

• IDRECOGNITION0005：使用多角度互動模式的高階防偽等級。該等級僅支援在Web SDK模式下使用，且目前該等級僅支援中國香港身份證。

"IDRECOGNITION0002"

operationMode

String

32

否

STANDARD

為身分識別驗證配置操作模式。取值如下：

• CLOSED：所有的演算法和風控規則都未開啟。該操作模式可用於測試情境，測試進程不受演算法和風控規則的影響。

• STANDARD：推薦的標準模式。

• LOOSE：相對寬鬆的模式，可用於低風險情境。

• STRICT：相對嚴格的模式，可用於高風險情境。

"STANDARD"

h5ModeConfig

H5ModeConfig

-

否

null

H5 ID Recognition的配置資訊。詳細資料，請參見H5ModeConfig。

說明：當metaInfo的值為MOB_H5時必須傳入該欄位。

{ "completeCallbackUrl":"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html", "interruptCallbackUrl":"http://xxx.html" }

productConfig

ProductConfig

-

否

null

為IDR產品提供更精細化的控制。詳細資料，請參見ProductConfig。

參考請求樣本

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

state

String

128

否

transactionId欄位的值

用於恢複客戶內容相關的標識符。

您可以為該欄位設定任何值，當ZOLOZ SDK回調商戶的移動App時將該值作為參數進行傳遞。

"G000000005FID20200304000000000001570702"

completeCallbackUrl

String

128

是

-

當整個身分識別驗證完成時，為瀏覽器指定即將重新導向的回調URL。

"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html"

interruptCallbackUrl

String

128

是

-

當進程中斷時，為瀏覽器指定重新導向到的回調URL。

"http://xxx.html"

isIframe

String

1

否

N

是否需要在iframe中開啟網頁，如果需要設定為Y，否則設定為N。

"Y"

uiCfg

String

256

否

null

自訂UI配置，採用JSON字串格式。目前僅支援titlebarbgcolor、titlebartextcolor、buttoncolor和captureMode。

說明：如果將captureMode參數設定為landscape，SDK將切換到橫向採集模式。

"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\", \"captureMode\":\"landscape\"}"

enableUpload

String

1

否

N

是否允許從案頭上傳檔案擷取證件圖片。取值：

• Y：允許從案頭上傳檔案擷取證件圖片。

• N：不允許從案頭上傳檔案擷取證件圖片。

注意：

• enableUpload必須與isDesktop一起使用。

• 如果enableUpload為Y，則isdesktop也必須為Y，否則系統將返回INVALID_ARGUMENT。

"Y"

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

特別說明

樣本值

cropDocImage

String

1

否

N

是否額外返回一張裁剪掉證件背景的證件圖片。取值如下：

• Y：是，如果同時採集了證件的正面和背面圖片，則會額外返回兩張裁剪後的圖片。

• N：否

-

"Y"

landmarkCheck

Array

-

否

null

在證件防偽檢測中進行landmark檢查，詳細檢查項，請參見證件防偽檢測組件。

說明：landmark檢查僅適用於大馬卡（MyKad）。

-

[

     {"name":"kadPengenalan"},

     {"name":"mykadLogo"},

     {"name":"flagLogo"},

     {"name":"mscLogo"},

     {"name":"ghostFace"},

     {"name":"hibiscusLogo"},

     {"name":"coatOfArm"},

     {"name":"twinTower"}

   ]

hologramCheck

Array

-

否

null

在證件防偽檢測中進行全息圖檢查，詳細檢查項，請參見證件防偽檢測組件。

說明：全息圖檢查僅適用於大馬卡（MyKad）。

-

[

   {

       "name": "hologram"

   }

]

pageInfoCheck

Array

-

否

null

在證件防偽檢測中進行頁面資訊檢查，詳細檢查項，請參見證件防偽檢測組件。

說明：頁面資訊檢查僅適用於中國香港身份證。

-

[

     {"name":"id"},

     {"name":"symbol"},

     {"name":"name"}

   ]

consistencyCheck

List<ConsistencyCheckItem>

-

否

null

是否在證件防偽檢測中進行一致性檢查。一致性檢查僅適用於部分證件的特定欄位，詳見ConsistencyCheckItem。

-

[

     {

       "type": "commonConsistencyCheck"

     },

     {

       "details": [

         "NAME",

         "SEX"

       ],

       "type": "mrzVisualConsistencyCheck"

     }

   ]

riskMode

String

10

否

STANDARD

ID Recognition中的多維度風控規則校正，用於攔截可疑交易。取值：

• CLOSED：關閉風控冷卻規則。該等級適用於測試情境，測試進程不受風控規則的影響。

• STANDARD：推薦的標準等級。

• LOOSE：相對寬鬆的等級，可用於低風險情境。

• STRICT：相對嚴格的等級，可用於高風險情境。

-

"STANDARD"

allowExpiredDocument

String

-

否

不同的證件類型有不同的預設值：

• Y：除護照（docType=00000001003）外的所有證件

• N：護照（docType=00000001003）

已到期的證件是否可以通過驗證。取值：

• Y：已到期的證件可以通過驗證。

• N：已到期的證件不能通過驗證。當檢測到證件到期時，IDR流程會失敗。

說明：

• 如果傳入除Y和N之外的值，系統將返回INVALID_ARGUMENT。

• 對於中國香港一代身份證（docType=08520000001），其到期攔截邏輯將嚴格依據香港政府身份證換領計劃執行。

-

"N"

cropFaceImageFromDoc

String

1

否

N

是否從採集的證件圖片中裁剪出人臉圖片。取值如下：

• Y：是

• N：否

-

"Y"

enableOCR

String

-

否

N

是否開啟OCR功能。取值如下：

• Y：開啟

• N：不開啟

注意：需要先購買OCR產品，才能使用該功能。

-

"Y"

docUiType

String

20

否

• Native SDK：2

• Web SDK：3

證件照片的採集方式。取值如下：

• 1：手拍版（Self-capture），使用者需要手動拍攝證件照片，僅具備基礎防偽能力。

• 2：Native防偽版（Deep-scan），僅適用於Native SDK。ZOLOZ SDK將自動對齊並拍攝證件照片，具備攔截彩打等進階防偽能力。

• 3：H5掃描版（Auto-scan），僅適用於Web SDK。ZOLOZ SDK將自動對齊並拍攝證件照片，僅具備基礎防偽能力。

  建議Web SDK使用自動掃描的採集方式，因為與手拍版相比，自動掃描的使用者體驗更好且證件圖片品質更高。

• 4：甩證版（Trace-scan），僅適用於Native SDK。當ZOLOZ SDK在網路攝影機範圍內檢測到證件時將自動拍攝。該版式可用於提升使用者體驗，但防偽能力較弱，僅具備基礎防偽能力。

• 5：多角度版（Multi-angle），僅適用於Web SDK中的中國香港證件。使用者需要分別拍攝正對證件的照片和證件傾斜30°的照片，具備攔截彩打等進階防偽能力。

說明：Deeper功能依賴Deep-scan和Auto-scan這兩種採集方式。當開啟Deeper功能時，為確保最佳檢測效果，請根據您的實際應用情境選擇對應的採集方式，Native端使用Deep-scan，H5端使用Auto-scan，否則會影響檢測效果。

以下三個參數的優先順序高於serviceLevel和operationMode。如果傳入了以下參數中的任意一個，其他參數的預設值都會生效。此時即使傳入了servicelevel和operationmode的值，這兩個參數也不會生效。

• docUiType

• spoofMode

• deeperMode

"2"

spoofMode

String

10

否

CLOSED

證件防偽等級。取值如下：

• CLOSED：所有的防偽演算法都未開啟。該等級可用於測試情境，測試進程不受演算法的影響。

• STANDARD：推薦的標準等級。

• LOOSE：預留等級，暫不支援使用。

• STRICT：預留等級，暫不支援使用。

注意：需要先購買Spoof產品，才能使用該功能。

"STANDARD"

deeperMode

String

10

否

CLOSED

AIGC攻擊檢測的Deeper等級，Deeper檢測功能的詳細介紹，請參見什麼是Deeper。該參數支援以下取值：

• CLOSED：Deeper的所有能力均不開啟，例如AIGC檢測演算法、終端風險檢測等。如果業務情境不需要AIGC攻擊檢測，則無需開啟。

• STANDARD：推薦的標準等級。

• LOOSE：相對寬鬆的等級，可用於低風險情境。

• STRICT：相對嚴格的等級，可用於高風險情境。

注意：需要先購買Deeper產品，才能使用該功能。

"STANDARD"

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型

OCR一致性檢查支援欄位

type

String

commonConsistencyCheck

對證件防偽檢測中的OCR欄位進行一致性檢查。

大馬卡 / 馬來西亞 / 00600000001

• 證件正面：ID_NUMBER

• 證件背面：ID_NUMBER_BACK前12位元字

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型

OCR一致性檢查支援欄位

type

String

mrzVisualConsistencyCheck

對證件防偽檢測中機讀區和視讀區的OCR欄位進行一致性檢查。

-

-

details

List<String>

請參見Real ID和ID Recognition支援的證件類型和返回的OCR結果。

在詳細資料中指定OCR欄位進行一致性檢查。

• 當type設定為mrzVisualConsistencyCheck時，必須傳入details欄位，且details不可為空。

• 僅允許傳入證件類型所支援的OCR欄位。

MyVisa / 馬來西亞 / 00600000011

• NAME

• SEX

護照（含機讀區和視讀區）/ 中國大陸、中國香港、中國台灣、中國澳門、菲律賓、新加坡、馬來西亞 / 00000001006

• ID_NUMBER

• COUNTRY_CODE

• EXPIRY_DATE

• DATE_OF_BIRTH

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型 / OCR一致性檢查支援欄位 / 預設國家代碼

type

String

passportCountryCheck

檢查OCR結果中的COUNTRY_CODE與系統檢測到的國家是否一致。

-

valueRange

List<String>

應與預設國家代碼一致

OCR結果中的COUNTRY_CODE應在valueRange範圍內。

當type設定為passportCountryCheck時，必須傳入valueRange欄位，各證件支援的valueRange，詳見Real ID和ID Recognition支援的證件類型和返回的OCR結果。

以下證件的valueRange為證件所屬國家或地區對應的預設國家或地區代碼所組成的列表。

• 中國大陸護照 / 00860000888 / COUNTRY_CODE / CHN

• 中國台灣護照 / 08860000002 / COUNTRY_CODE / TWN

• 中國澳門護照 / 08530000002 / COUNTRY_CODE / CHN

• 菲律賓舊版護照 / 00630000031 / COUNTRY_CODE / PHL

• 菲律賓新版護照 / 00630000032 / COUNTRY_CODE / PHL

每一項都應符合ISO_3166-1_alpha-3標準

以下證件的valueRange為列表，且每一項都應符合ISO_3166-1_alpha-3標準。

• 國際護照（僅含機讀區） / 00000001003 / COUNTRY_CODE

• 國際護照（含機讀區和視讀區）/ 00000001006 / COUNTRY_CODE

欄位名稱

資料類型

必須返回

描述

樣本值

result

Result

是

API請求結果，包含結果狀態、結果碼和結果訊息。

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

否

ZOLOZ伺服器為證件識別進程產生的唯一事務ID。此ID將作為ID Recognition checkresult API請求的輸入參數。

說明：僅當交易進入處理階段後系統才會返回transactionId。如果在開始處理交易之前發生錯誤，系統不會返回transactionId。包括但不限於以下情況：

• 請求參數非法，例如入參格式錯誤或缺失必傳參數。

• 請求未能成功到達伺服器，例如網路問題或網關故障。

• 系統限流導致請求被拒絕。

"G000000005FID20200304000000000001570702"

clientCfg

String

否

用戶端配置資訊，包括SDK串連和行為參數。

說明：當result.resultStatus的值為S時，才返回該欄位。

"……"

結果碼

結果狀態

描述

SUCCESS

S

API調用成功。

HIGH_RISK

F

檢測到高風險。使用者帳號被風險引擎凍結。

ACCOUNT_SERVICE_SUSPEND

F

使用者帳號被風險引擎列入黑名單。

DEVICE_NOT_SUPPORT

F

不支援當前的裝置類型。

OS_NOT_SUPPORT

F

不支援當前裝置的作業系統。

SDKVERSION_NOT_SUPPORT

F

不支援ZOLOZ SDK當前的版本。

INVALID_ARGUMENT

F

輸入參數無效。關於無效參數的詳細資料，請查看返回的resultMessage。

SYSTEM_ERROR

F

其他內部錯誤。有關錯誤詳情，請查看返回的resultMessage。