Two-Factor Verify API

Important Notice:

  • All request and response parameters are strictly subject to the official API documentation.
  • The API response may contain fields not defined in the documentation. These fields are for internal debugging purposes only and are not guaranteed to be stable or compatible. Do not rely on these fields in production environments. ZOLOZ reserves the right to modify or remove these fields at any time without prior notice.

Overview

  • API URL: /api/v1/zoloz/cnauthority/twofactor/verify
  • This API performs two-factor (name + ID number) identity verification against the China mainland authority database. It only verifies the consistency between the name and the ID number, and does not collect or transmit a facial photo. This API uses a synchronous request-response model and does not support idempotent invocation; each invocation generates a new transactionId.

Note: Billed when resultCode is SUCCESS or AUTHORITY_NOT_SAME_PERSON.

Request parameters

Field name

Data type

Max length

Required

Default value

Description

Example

bizId

String

32

Yes

-

A unique business ID for tracing purposes, for example, a serial number from the merchant's business-related database.

Note:

The ZOLOZ server does not perform uniqueness checks on the value of this field. To make business tracking easier, it is recommended to enable the merchant server and ensure the uniqueness of the business ID.

"verify2-bizid-001"

idName

String

32

Yes

-

The user's real name to be verified.

Note:

  • Provide the name exactly as it appears on the valid identity document, including rare characters and polyphonic characters.
  • If the name contains spaces, the authority database determines their validity; this API does not perform pre-validation.

"Zhang San"

idNo

String

32

Yes

-

The ID number to be verified.

Note:

  • Letters must be uppercase, e.g. 42050219881229801X.
  • This API does not validate the format of the ID number (e.g., check digit, length); format validation is performed by the authority database. A lowercase x will be treated as an invalid ID number by the authority database.

"42050219881229801X"

Response parameters

Field name

Data type

Required

Description

Example

result

Result

Yes

The API request result object, containing resultCode, resultStatus and resultMessage.

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

transactionId

String

No

The unique transaction ID generated by the platform, in the format G+18 digits. It can be used to query the verification record in zmng/portal. Note:

  • Returned when the verification succeeds or enters the processing state.
  • May not be returned if the API call fails (e.g., invalid input, system error).

"G000000000FCTF20261106000000205019269449"

Result process logic

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

  • If the value of the result.resultStatus field is S, the verification is successful and the name and ID number are consistent.
  • If the value of the result.resultStatus field is F, the verification 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 error codes

The following table shows the possible error codes that are specific for the CN Authority Two-Factor Verify API. Billed when resultCode is SUCCESS or AUTHORITY_NOT_SAME_PERSON.

resultCode

resultStatus

Description

Billed

SUCCESS

S

Verification successful. The name and ID number are consistent.

Yes

AUTHORITY_NOT_SAME_PERSON

F

The name and ID number are inconsistent.

Yes

AUTHORITY_PROCESSING

F

Verification is still in progress. Please retry later.

No

AUTHORITY_INACTIVE

F

The merchant has not activated (or has deactivated) the China Authority service.

No

AUTHORITY_PRODUCT_NOT_OPEN

F

The CTF product is not activated. Please contact the ZOLOZ operations team to enable this product.

No

AUTHORITY_INVALID_CERT_NAME

F

Invalid name (e.g., contains characters that cannot be recognized or a format that does not meet the authority database requirements).

No

AUTHORITY_INVALID_CERT_NO

F

Invalid ID number (e.g., incorrect length, illegal format or wrong check digit).

No

AUTHORITY_HIGH_RISK

F

The request is determined to be high risk. Manual review is recommended.

No

Sample

Request sample

copy
{
  "bizId": "verify2-bizid-001",
  "idName": "Zhang San",
  "idNo": "42050219881229801X"
}

Response sample

Verification consistent

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

Verification inconsistent

copy
{
  "result": {
    "resultCode": "AUTHORITY_NOT_SAME_PERSON",
    "resultStatus": "F",
    "resultMessage": "not same person"
  },
  "transactionId": "G000000000FCTF20261106000000205019269449"
}