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:
| "Zhang San" |
idNo | String | 32 | Yes | - | The ID number to be verified. Note:
| "42050219881229801X" |
Response parameters
Field name | Data type | Required | Description | Example |
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
| "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
{
"bizId": "verify2-bizid-001",
"idName": "Zhang San",
"idNo": "42050219881229801X"
}
Response sample
Verification consistent
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
},
"transactionId": "G000000000FCTF20261106000000205019269449"
}
Verification inconsistent
{
"result": {
"resultCode": "AUTHORITY_NOT_SAME_PERSON",
"resultStatus": "F",
"resultMessage": "not same person"
},
"transactionId": "G000000000FCTF20261106000000205019269449"
}