ZOLOZZOLOZDOCS

checkresult

Overview

  • API URL: /api/v1/zoloz/nfc/checkresult
  • API Description: This interface is used to obtain the operational status of the NFC reading process and related identification results, including ID details, face details, etc.

Note: This API supports repeated calls i.e. this API is idempotent. After obtaining results, please do not call this API excessively as it will cause traffic surge and trigger flow limitation, affecting the normal use of other API calls.

Structure

Request parameters 

Field name

Data type

Max length

Description

Example

bizId

String

32

Required. A unique business ID for tracing purposes. For example, the sequence ID from the merchant's business-related database.

Note: The ZOLOZ server does not perform uniqueness checks on the value of this field. For better tracking, it is strongly recommended to enable the merchant server to guarantee the uniqueness of the business ID. 

"2017839040588699"

transactionId

String

64

Required. The unique transaction ID that is returned by the response from the ZOLOZ NFC initialize API. 

"G000000005FID20200304000000000001570702"

isReturnImage

String

1

Optional. Specifies whether to return the image data in the response. The following values are supported: 

  • Y: Returns the image data in the response.
  • N: Does not return the image data in the response.

Note: By default, the value N is used. 

"Y"

Response parameters 

Note: nfcResult, extBasicInfo, extFaceInfo and extIdInfo fields are returned only when the value of result.resultStatusis S.

Field name

Data type

Description

Example

result

Result

Required. The API request result, which contains information about the result of the API request, such as status and error codes. 

{ 

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

}

nfcResult

String

Optional. Specifies the running status of the whole NFC reader process. The following values are supported: 

  • Success: The NFC reading process runs successfully.
  • Pending: The NFC reading process is pending.
  • Failure: The NFC reading process has failed.
  • InProcess: The NFC reading process is in progress.
  • VoidCancelled: The NFC reading process has been cancelled.
  • VoidTimeout: The NFC reading process has timed out.

"Pending"

extBasicInfo

ExtBasicInfo

Optional. Basic real-name information. 

{ 

"certNo":"E40431234", "certType":"00000001003", "certName":"SAN ZHANG" }

extFaceInfo

ExtFaceInfo

Optional. Detailed face information.

{ "faceImg":"/9j/4AAQSkZJRgABAQAAA..." }

extIdInfo

ExtIdInfo

Optional. Detailed document information.

{ "frontPageImg":"/9j/4AAQSkZ...", "personInfoResult":{ "ID_NUMBER":"E40431234", "SEX":"M", "LAST_NAME":"ZHANG", "DATE_OF_BIRTH":"891028", "FIRST_NAME":"SAN", "EXPIRY_DATE":"330419", "COUNTRY_CODE":"CHN" 

}, 

"docEdition":1 }

extRiskInfo

ExtRiskInfo

Optional. Detailed information about risk control. 

*Note: This field is an expired field and will be deleted soon. No data will be returned, please ignore it. 

-

extCancelInfo

ExtCancelInfo

Optional. Detailed information about user cancellations in the NFC Reader. 

*Note: This field is an expired field and will be deleted soon. No data will be returned, please ignore it. 

-

ExtBasicInfo

Note: certType, certNo and certName fields are returned only when the document has been successfully recognized.

Field name

Data type

Description

Example

certType

String

Optional. Document type. 

"00000001003"

certNo

String

Optional. The document number i.e. the document number from which the document can be identified from.

"E40431234"

certName

String

Optional. Name i.e. the name identified from the document. 

"SAN ZHANG"

ExtFaceInfo

Field name

Data type

Description

Example

faceImg

String

Optional. The face information read from the ID chip, usually in JPEG2000 format. 

Note: This field is returned only when the value of isReturnImage is Y and the ID has been recognized successfully. 

"/9j/4AAQSkZJRgABAQAAA..."

ExtIdInfo

Field name

Data type

Description

Example

frontPageImg

String

Optional. The front of the ID photo in Base64 encoded format. 

Note: This field is returned when the value of isReturnImage is Y and the document is recognized successfully. The image format is JPG. 

"/9j/4AA..[omitted]..PxA="

personInfoResult

Map

Optional. Identity information stored by NFC. The identity information returned varies from one document to another, see PersonInfoResult for more details. 

Note: This field is returned when the document is successfully recognized. 

{ "ID_NUMBER":"E40431234", "SEX":"M", "LAST_NAME":"ZHANG", "DATE_OF_BIRTH":"891028", "FIRST_NAME":"SAN", "EXPIRY_DATE":"330419", "COUNTRY_CODE":"CHN" }

docEdition

Integer

Optional. The identity document version. By default, this value is 1. 

1

PersonInfoResult 

00000001003 (Passport)

Field name

Data type

Description

Example

FIRST_NAME

String

Name

"SAN"

LAST_NAME

String

Surname

"ZHANG"

SEX

String

Sex

"M"

ID_NUMBER

String

ID number

"E40431234"

DATE_OF_BIRTH

String

Date of birth in yyMMdd format.

"891028"

EXPIRY_DATE

String

Expiry date in yyMMdd format.

"330419"

COUNTRY_CODE

String

Country code

"CHN"

00860000011 (Travel Permit for Mainland China Residents to and fro Hong Kong and Macau)

Field name

Data type

Description

Example

NAME

String

Western name

"ZHANG SAN"

NAME_CN

String

Chinese name

"张三"

SEX

String

Sex

"M"

ID_NUMBER

String

ID number

"E40431234"

DATE_OF_BIRTH

String

Date of birth in yyMMdd format.

"891028"

EXPIRY_DATE

String

Expiry date in yyMMdd format.

"330419"

Result 

Result process logic 

For different request results, different actions will be performed. See the following for details:

  • If the value of the result.resultStatus is S , the ZOLOZ NFC Reader checkresult API is invoked successfully and a unique transaction ID is returned.
  • If the value of the result.resultStatus is F , the invocation of the ZOLOZ NFC Reader checkresult API fails. Check the error code and its message for more information on the possible reasons why.

Common error codes

For the full list of common error codes, see the Common error codes section in the Error handling topic. 

API-specific result codes 

The following table shows the possible error codes that are specific to the ZOLOZ NFC checkresult API.

Field name

Data type

Description

SUCCESS

S

The API call is successful.

INVALID_ARGUMENT

F

Input parameters are invalid. For more information about which parameter is invalid, check the result message or the related log. 

SYSTEM_ERROR

F

Other internal errors. For more information about the error details, check the result message or the related log. 

Samples

Request sample

The following sample shows what a request sent from the merchant server looks like. 

copy
{
    "bizId": "2017839040588699",
    "transactionId": "G000000005FID20200304000000000001570702",
    "isReturnImage": "Y"
}

Response sample 

The following sample shows what a response returned from the ZOLOZ server looks like. 

copy
{
    "result":{
        "resultStatus":"S",
        "resultCode":"SUCCESS",
        "resultMessage":"Success"
    },
    "extRiskInfo":{
    },
    "nfcResult":"Success",
    "extFaceInfo":{
        "faceImg":"/9j/4AAQSkZJRgABAQAAA..."
    },
    "extBasicInfo":{
        "certNo":"E40431234",
        "certType":"00000001003",
        "certName":"SAN ZHANG"
    },
    "extCancelInfo":{
    },
    "extIdInfo":{
        "frontPageImg":"/9j/4AAQSkZ...",
        "personInfoResult":{
            "ID_NUMBER":"E40431234",
            "SEX":"M",
            "LAST_NAME":"ZHANG",
            "DATE_OF_BIRTH":"891028",
            "FIRST_NAME":"SAN",
            "EXPIRY_DATE":"330419",
            "COUNTRY_CODE":"CHN"
        },
        "docEdition":1
    }
}