eKYC_PRO_App_CheckResult - ID Verification - Alibaba Cloud Documentation Center

This topic describes how to call the CheckResult operation to query the authentication results of the eKYC_PRO solution.

API description

Operation name: CheckResult
Request method: HTTPS POST
Description: After you receive a callback notification, you can call this operation on the server to retrieve the authentication status and materials.
Important
By default, ID Verification service results are stored for 30 days and then automatically deleted. You must retrieve the verification results within 30 days.
This API operation has a dedicated QPS limit. For more information, see QPS limits for ID Verification server-side API operations.
Service endpoint:
Note
- Benefits of internal network access: An internal network is a private communication network between Alibaba Cloud products within the same region. If your business server is deployed in the corresponding Alibaba Cloud region, you can use the internal same-region endpoint to access the ID Verification service. This provides more secure and stable communication.
- Optimization suggestions for access from outside China: Network environments outside China can be complex. To optimize your integration solution, reduce network latency, and minimize request failures, see Server-side network latency analysis and optimization.
Singapore
- Public network: cloudauth-intl.ap-southeast-1.aliyuncs.com
- Internal network: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com
Indonesia
- Public network: cloudauth-intl.ap-southeast-5.aliyuncs.com
- Internal network: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com
China (Hong Kong)
- Public network: cloudauth-intl.cn-hongkong.aliyuncs.com
- Internal network: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
Malaysia (Kuala Lumpur)
- Public network: cloudauth-intl.ap-southeast-3.aliyuncs.com
- Private network: cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

Online debugging and integration

Note

Before you debug and integrate an API operation, see Debug and integrate server-side API operations using OpenAPI Explorer for information about how to call API operations and obtain SDKs and sample code in OpenAPI Explorer.

You can test this operation in OpenAPI Explorer, and generate sample SDK code.

Request parameters

Name	Type	Required	Description	Example value
MerchantBizId	String	Yes	A unique business ID that you customize. It helps locate and troubleshoot issues later. Use a combination of letters and digits up to 32 characters long. Ensure the ID is unique. Note Alibaba Cloud servers do not check whether this field's value is unique. To improve tracking, ensure the field value is unique.	e0c34a77f5ac40a5aa5e6ed20c35****
TransactionId	String	Yes	The unique identifier for the entire verification flow. Call the Initialize API operation to obtain this value. Important To prevent tampering, use the TransactionId stored on your server when you call the Initialize operation. Do not use the TransactionId returned by the client-side callback.	hksb7ba1b28130d24e015d6********
IsReturnImage	String	No	Specifies whether to return the authentication image materials: Y : required N: No (default)	Y

Returned Data

Name		Type	Description	Example value
HTTP Status Code		Integer	The HTTP status code.	200
HTTP Body	RequestId	String	The request ID.	130A2C10-B9EE-4D84-88E3-5384FF039795
	Code	String	The response code.	Success
	Message	String	The detailed description of the response code.	success
	Result.Passed	String	The final authentication result. Valid values: Y: Passed N: Failed	Y
	Result.SubCode	String	The description of the authentication result. For more information, see Error codes for ResultObject.SubCode.	200
	Result.ExtFaceInfo	String	Information about the face liveness verification results. For the JSON format, see the example on the right. For more information, see ExtFaceInfo.	`{ "faceAttack": "N", "faceComparisonScore": 99.99, "faceImg": "base64 format", "facePassed": "Y", "faceQuality": 95.45, "faceOcclusion": "N" "docVideoUrl": "https://aliyun-cloudauth.oss-aliyuncs.com/******.webm" }`
	Result.ExtIdInfo	String	Information about certificate detection results. For the JSON format, see the example on the right. For more information, see ExtIdInfo.	`{ "ocrIdInfoData": { "01": { "ocrIdInfo": { "id_number": "083099003767", "full_name": "MAC PHAM HOÀNG DƯƠNG", "nationality": "Việt Nam", "date_of_expiry": "", "date_of_birth": "16/08/1999", "sex": "Nam" }, "ocrIdPassed": "Y", "spoofInfo": { "spoofResult": "N" } }, "02": { "ocrIdInfo": { "date_of_issue": "10/02/2022", "personal_identification": "Sẹo chấm C.2cm trên sau mèp phải" }, "ocrIdPassed": "Y", "spoofInfo": { "spoofResult": "N" } } }, "ocrIdPassed": "Y" }`
	Result.ExtSourceInfo	String	The following describes the details of the data source verification results. The Indonesian data source is used as an example. govId, fullName, dob: A comparison score of 1.0 indicates a complete match with the official data source information. A score below 1.0 indicates a mismatch. selfiePhoto: A comparison score greater than 0.8 indicates a match with the official data source information. A score of 0.8 or lower indicates a mismatch. liveness: A score higher than 0.95 indicates a liveness detection risk. imgManipulationScore: A score higher than 0.95 indicates an image tampering risk.	`{ "govId": 1.0, "fullName": 1.0, "dob": 0.9, "selfiePhoto": 0.8777, "liveness": 0.1152, "imgManipulationScore": 0.2253 }`

ExtFaceInfo

Name	Type	Description	Example
facePassed	String	The final result of the face liveness verification. Y: Passed N: Failed	Y
faceComparisonScore	Double	The similarity score of the face comparison between the captured face and the face on the certificate. The value ranges from 0 to 100.	99.99
faceImg	String	The captured face image in Base64 format. This field is returned if you set `IsReturnImage` to Y in the request and the face scan is completed.	Base64 format
faceAttack	String	Indicates whether a liveness attack was detected on the captured face. Y: An attack was detected. N: No attack was detected.	N
docVideoUrl	String	The OSS download URL for the evidence video. Note The URL for the evidence video is valid for 15 minutes. You can query and obtain the video repeatedly within 30 minutes after the authentication is complete. After 30 minutes, the system automatically deletes the evidence video file. The file cannot be recovered. Download and save the file promptly.	https://aliyun-cloudauth.oss-aliyuncs.com/******.webm
faceAge	String	The predicted reference age based on the face image. This field may not be returned if the prediction fails.	30
faceGender	String	The predicted gender based on the face image. This field may not be returned if the prediction fails. M: Male F: Female	M
faceAttackScore	Double	The probability of a spoofing attack predicted by the facial recognition algorithm. A higher score indicates a higher probability of a spoofing attack. The value ranges from 0 to 100.	80
guardRiskScore	Double	The probability of device risk predicted by the Face-Guard algorithm. A higher score indicates a higher device risk. The value ranges from 0 to 100.	90

ExtIdInfo

Name	Type	Description	Example value
ocrIdPassed	String	The final result of the certificate OCR recognition stage. Y: Passed N: Failed	N
ocrIdInfoData	Map<String,Object>	The detailed OCR information of the certificate. The key is the page number of the certificate. For more information about the value, see ocrIdInfoData. `01` and `02` indicate the front and back (or secondary page) of the certificate, respectively.	`{ "01": "ocrIdInfo": { "expiryDate": "2030.01.01", "englishName": "SUN, xxx", "originOfIssue": "National Immigration Administration, People's Republic of China", "placeOfIssue": "Beijing", "sex": "Male", "name": "Sun X", "idNumber": "CGxxxxxxxx", "issueDate": "2024.12.01", "birthDate": "1992.12.01" }, "ocrIdPassed": "Y", "spoofInfo": { "spoofResult": "N" } } }`
ocrIdEditInfo	String	The certificate OCR field information submitted by the user after editing on the OCR result page. This field is returned when the OCR result editing page (ShowOcrResult) is enabled in the client configuration.	`{ "expiryDate": "2026-01-02", "originOfIssue": "Bureau of Exit and Entry Administration of the Ministry of Public Security", "englishName": "ZHANG SAN", "sex": "Male", "name": "Zhang San", "idNumber": "H11111115", "issueDate": "2013-01-02", "birthDate": "1990-02-21" }`

ocrIdInfoData

Name	Type	Description	Example value
idImage	String	The certificate OCR photo in Base64 format. This field is returned if you set isReturnImage=Y in the request and the certificate OCR process completes successfully.	base64 format
ocrIdPassed	String	The result of the certificate OCR recognition stage for this page. Y: Passed N: Failed	N
ocrIdInfo	String	The certificate OCR field information. For more information about the fields, see Certificate OCR fields. Note If the certificate OCR process fails, this field is empty.	`{ "expiryDate": "2030.01.01", "englishName": "SUN, xxx", "originOfIssue": "National Immigration Administration, People's Republic of China", "placeOfIssue": "Beijing", "sex": "Male", "name": "Sun X", "idNumber": "CGxxxxxxxx", "issueDate": "2024.12.01", "birthDate": "1992.12.01" }`
spoofInfo	String	The result of the anti-spoofing detection for the certificate, including the risk result and risk type. Note Certificate detection is enabled only if you set IdSpoof to Y in the Initialize operation. Otherwise, spoofResult returns N by default and spoofType is empty. spoofResult: Y: A risk is detected. N: Normal spoofType: SCREEN_REMARK: Recapture PHOTO_COPY: Photocopy TAMPER: Tampered	`{ "spoofResult": "Y", "spoofType": ["SCREEN_REMARK"] }`

Response codes

HTTP status code	Code	Message description
200	Success	Request successful.
400	MissingParameter	Parameter cannot be empty.
	InvalidParameter	Invalid parameter.
	TransactionIdInvalid	Invalid Transaction ID.
403	Forbidden.RAMUserAccessDenied	You need to grant the RAM user the AliyunAntCloudAuthFullAccess permission. For more information, see Authorize RAM users to access the service.
	Forbidden.AccountAccessDenied	Ensure that you have activated ID verification and your account has no overdue payment.
	Throttling.Api	API request is blocked due to throttling.
404	ProcessNotCompleted	The entire authentication process is not completed.
500	InternalError	Internal system error. Provide feedback to engineers for troubleshooting.
503	ServiceUnavailable	The service is unavailable. Contact engineers for troubleshooting.

Error codes for ResultObject.SubCode

Error code	Is authentication record billed?	Description and suggested reasons
200	Yes	Authentication passed.
202	Yes	The national ID number is not in the authoritative data source.
204	Yes	Liveness face and selfie photo do not match. This may be due to a person-document mismatch or low-quality liveness photo.
205	Yes	Risk detected in liveness detection.
206	Yes	Business policy restriction. When safe mode is enabled, security checks are performed on the authentication device and environment. If risks are detected, the authentication fails. Troubleshooting steps: Remind users to uninstall any app cloners, parallel space apps, virtual environments, or related plugins from their devices. Restore the device to its original secure environment and try again. Check if you are using a test demo package name. If so, change it to your business package name to avoid being blocked by engineering or service security policies.
207	Yes	The selfie photo doesn't match the information in the authoritative data source.
209	Yes	Authoritative data source timeout.
212	Yes	Document anti-counterfeiting detection indicates risk. High-risk operations detected, such as re-capturing (taking a photo of a screen/photo ), tampering, or photocopying.
214	Yes	The personal information (national ID number, name, date of birth) doesn't match the information in the authoritative data source.
215	Yes	Neither the personal information (national ID number, name, date of birth) nor the selfie photo matches any records in the authoritative data source.
216	Yes	Authoritative data source detected a liveness anomaly. This can occur during verification with the Indonesian data source if the `ExtScoureInfo` field has a `liveness` value greater than 0.95, or an `imgManipulationScore` value greater than 0.95.
217	Yes	The quality of the selfie photo doesn't meet the requirements.
218	Yes	The eKYC process has passed but failed to use the authoritative data source.

API description

Singapore

Indonesia

China (Hong Kong)

Malaysia (Kuala Lumpur)