Connect APIs

    #API Overview

    Please note these APIs are exposed via ZOLOZ Gateway. Please refer to the ZOLOZ Gateway Document for the correct way of invocation. 

    API Name

    Description

    v1.zoloz.connect.initialize

    This will initialize a verification application in ZOLOZ with a unique transaction ID, which shall be used in all the subsequent interactions with ZOLOZ for the same application.

    v1.zoloz.connect.checkresult

    This is for your server side to retrieve the verification result no matter the verification process is completed successfully or not.

    v1.zoloz.connect.enroll

    This is used to enroll a face image of one user for subsequent usage of connect.

    #Initialize

    #Request Sample

    copy
    {
        "bizId": "2017839040588699",
        "userId": "merchant side user id",
        "sceneCode": "changePassword",
        "serviceLevel": "CONNECT0002",
        "metaInfo": "{
               \"deviceType\": \"deviceType\",
               \"appVersion\": \"1.0\",
               \"osVersion\": \"7.1.1\",
               \"appName\": \"com.alipay.android.zoloz.company\",
               \"bioMetaInfo\": \"3.37.0:262144,0\",
               \"apdidToken\": \"mock-apdidToken\",
               \"deviceModel\": \"MI 6\",
               \"zimVer\": \"2.0.0\"
          }"
    }


    #Request Fields Specification

    Name

    Type

    Max Length

    Mandatory

    Description

    Sample Value

    bizId

    String

    32

    Yes

    Uniquely generated, globally unique business ID, for tracing. e.g. Sequence ID from DB.

    2017839040588699

    metaInfo

    String

    512

    Yes

    Meta info from client.

    <metaInfoFromClient>

    userId

    String

    64

    Yes

    Merchant user id. Must be the same as enrolled information. Either userId or certInfo, one of them must be in the request.

    2305940069977

    sceneCode

    String

    64

    No

    Business scene for data analysis purpose, no real business impact.If you want to distinguish the data performance of different scenarios,we suggest setting sceneCode to different value.It is recommended to name sceneCode's value according to business purpose.For example: login, riskVerify, paymentchangePassword.

    changePassword

    serviceLevel

    String

    32

    No

    The service level, check following table for details.

    CONNECT0002


    The value range of "serviceLevel" at business level

    serviceLevel

    UI

    Description

    CONNECT0001

    Garfield

    This level has basic liveness detection ability. Because Garfield doesn't require user to jump to a new page, which makes less user drop off, it is usually used in the scenarios which require high pass rate

    CONNECT0002

    Cherry(Blink)

    Default level. This level has basic anti-spoofing ability and basic liveness detection ability

    CONNECT0003

    Cherry(Multi-action)

    This level has advanced anti-spoofing ability and basic liveness detection ability


    #Response Sample

    copy
    {
        "result": {
            "resultStatus": "S",
            "resultCode": "SUCCESS",
            "resultMessage": "Success"
        },
        "transactionId":"G006600016CN20190114000000009572520355", 
        "clientCfg": "……"   
    }


    #Response Fields Specification

    Name

    Type

    Mandatory

    Description

    Sample Value

    result

    Result

    Yes

    API result.


    result.resultStatus

    String

    Yes

    Result status.

    "S": Successful

    "F": Failed.

    S

    result.resultCode

    String

    Yes

    Result code. Refer to the table below for more information.

    SUCCESS

    result.resultMessage

    String

    Yes

    More information to describe the result code.

    success

    transactionId

    String

    No

    Unique ID that used to start Connect SDK in client side. Server side need to pass this to calling client for further processing. It will be provided when error is not on client side. For example, invalid arugment won't have transactionId.

    G006600016CN20190114000000009572520355

    clientCfg

    String

    No

    Client config to be used by Zoloz SDK.



    The value range of "resultCode" at business level: 

    resultCode

    Description

    SUCCESS

    Success.

    UNABLE_GET_IMAGE

    No reference source is found (caused by attempting to verify before enroll).

    HIGH_RISK

    The account is cooled down by the risk engine.

    ACCOUNT_SERVICE_SUSPENDThe account is blacklisted by the risk engine.
    DEVICE_NOT_SUPPORT

    The device is not supported.

    OS_NOT_SUPPORT

    The operating system version is not supported.

    SDKVERSION_NOT_SUPPORT

    The APP version is not supported.

    INVALID_ARGUMENT

    Invalid argument.

    SYSTEM_ERROR

    System error.



    #CheckResult

    #Request Sample

    copy
    {
        "bizId": "2017839040588699",
        "transactionId": "G006600016CN20190114000000009572520355",
    }


    #Request Fields Specification

    Name

    Type

    Max Length

    Mandatory

    Description

    Sample Value

    bizId

    String

    32

    Yes

    Uniquely generated, globally unique business ID, for tracing. e.g. Sequence ID from DB.

    2017839XXXXXX699

    transactionId

    String

    64

    Yes

    Unique ID that returned from initialize api.

    when error is client side

    like invalid argument, we won't return txnId

    G006600016CN20190114000000009572520355


    #Response Sample

    copy
    {
        "result": {
            "resultCode": "SUCCESS",
            "resultMessage": "Success",
            "resultStatus": "S"
        },
        "extFaceInfo": {
            "aliveImage": "#ALIVE_FACE_BASE64_CONTENT#",
            "refImage": "#REFERENCE_FACE_BASE64_CONTENT#",
            "faceScore": 89.1,
            "faceAttack": false
        }
    }


    #Response Fields Specification

    Name

    Type

    Mandatory

    Description

    Sample Value

    result

    Result

    Yes

    API result.


    result.resultStatus

    String

    Yes

    Result status at system level. "S" or "F". "S" stands for success and "F" stands for failure.

    S

    result.resultCode

    String

    Yes

    Detailed result code. Refer to the table below for more information.

    SUCCESS

    result.resultMessage

    String

    Yes

    Result details. Explanation to result code.

    Success

    extFaceInfo

    ExtFaceInfo

    No

    Detailed informationRefer to the table below for details.



    ExtFaceInfo Specification

    Name

    Fields Key

    Type

    Description

    Sample Value

    extFaceInfo

    aliveImage

    String

    Alive face image in base64 format, only presents when retCode equals SUCCESS or NOT_SAME_PERSON.


    refImage

    String

    Referenced face image in base64 format, only presents in a verification flow where retCode equals SUCCESS or NOT_SAME_PERSON.


    faceScore

    double

    Face matching similarity, only presents in a verification flow where retCode equals SUCCESS or NOT_SAME_PERSON.

    89.1

    faceAttack

    boolean

    Attack detected, only presents when retCode equals SUCCESS or NOT_SAME_PERSON. Possible values will be: true/ false.

    true


    The value range of "resultCode" at business level: 

    resultCode

    Description

    SUCCESS

    Success.

    INVALID_ARGUMENT

    Invalid argument.

    SYSTEM_ERROR

    System error.

    NOT_SAME_PERSON

    Authentication fails because similarity score is lower than threshold or spoofing behavior/high risk behavior is detected.

    UNABLE_GET_IMAGE

    Enrolled image is not available or invalid.

    PROCESSING

    The authentication is still in processing.


    #Enroll

    #Request Sample

    copy
    {
        "bizId":"2017839040588699",
        "userId":"merchant side user id", 
        "base64ImageContent":"xxxxxxxxxxxxxxxxx"
    }


    #Request Fields Specification

    Name

    Type

    Max Length

    Mandatory

    Description

    Sample Value

    bizId

    String

    32

    Yes

    Uniquely generated, globally unique business ID, for tracing. e.g. Sequence ID from DB.

    2017839040588699

    userId

    String

    64

    Yes

    Merchant user id. Must be the same as enrolled information. Either userId or certInfo, one of them must be in the request.

    2305940069977

    base64ImageContent

    String


    Yes

    Image content using base64 encode



    #Response Sample

    copy
    {
        "transactionId": "G006600016CN20190114000000009572520355",
        "result": {
            "resultStatus": "S",
            "resultCode": "SUCCESS",
            "resultMessage": "Success"
        }
    }


    #Response Fields Specification

    Name

    Type

    Mandatory

    Description

    Sample Value

    result

    Result

    Yes

    API result.


    result.resultStatus

    String

    Yes

    Result status.

    "S": Successful

    "F": Failed.

    S

    result.resultCode

    String

    Yes

    Result code. Refer to the table below for more information.

    SUCCESS

    result.resultMessage

    String

    Yes

    More information to describe the result code.

    success

    transactionId

    String

    No

    Unique ID that used to for this enroll request. It will be provided when if error is not on client side. For example invalid argument won't have transactionId.

    G006600016CN20190114000000009572520355


    The value range of "resultCode" at business level:

    resultCode

    Description

    SUCCESS

    Success.

    UNABLE_GET_IMAGE

    Cannot extract face feature from requested image.

    INVALID_ARGUMENT

    Invalid argument.

    SYSTEM_ERROR

    System error.