This topic describes how to use EkycVerify API.
Interface description
Interface name: EkycVerify.
Service address: cloudauth-intl.cn-hongkong.aliyuncs.com.
Request method: HTTPS POST.
Interface description: Call the EkycVerify interface to perform eKYC authentication on input identity related materials.
Request parameters
Parameter | Type | Required | Description | Example |
ProductCode | String | Yes | Product code of eKYC solution via pure API interface. eKYC_ MIN. | eKYC_MIN |
MerchantBizId | String | Yes | A unique business ID for tracing purpose. For example, the sequence ID from the merchant's business-related database. Note The Alibaba Cloud server does not perform uniqueness check 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. | e0c34a77f5ac40a5aa5e6ed20c35**** |
MerchantUserId | String | Yes | Merchant user ID, or other identifiers that can be used to identify a specific user, for example, mobile phone number, email address and so on. It is strongly recommended to pre-desensitize the value of the userId field, for example, by hashing the value. | 123456789 |
IdOcrPictureBase64 | String | No | Front image of ID card, binary stream base64 encoding. Note IdOcrPictureBase64 or IdOcrPictureUrl need to be set. If you choose IdOcrPictureBase64 to transfer ID image, please ensure the size of the image is not too large. | base64 |
IdOcrPictureUrl | String | No | The HTTPS or HTTP address of the image of the front side of ID card. | https://*** |
DocType | String | Yes | Document type, consisting of 8 digits, with mapping detailed in the DocType List. | 01000000 |
FacePictureBase64 | String | No | Face Images Base64 encoded. Note FacePictureBase64 or FacePictureUrl need to be set. | base64 |
FacePictureUrl | String | No | The HTTPS or HTTP address of the face image. | https://*** |
DocName | String | No | The real name of the user. Note When Authorize=T and the input document type is China Resident Identity card, at least one set of key input below is necessary:
| Zhang san |
DocNo | String | No | The ID number of the identity documents. Note When Authorize=T and the document type is China Mainland ID card, at least one set of key input below is necessary:
| 411xxxxxxxxxxx0001 |
Crop | String | No | Whether to enable the face image cropping so that the detected face is used as the center of the derived picture. The following values are supported:
By default, the value of F is used. | F |
Authorize | String | No | Whether to enable the identity validation using authority databases. The following values are supported:
By default, the value of F is used. Note Only applicable to China Resident Identity Card. | F |
DocType List
DocType | CertType |
01000000 | Passport for all countries. |
00000006 | HKID 2003 version (Hong Kong Identity Card). |
00000008 | HKID 2018 version (Hong Kong Identity Card). |
00000007 | China Exit-Entry Permit for Travelling to and from Hong Kong(China) and Macao. |
00000009 | China Mainland Travel Permit for Hong Kong and Macao Residents. |
000000011 | Macau Identity Card. |
000000012 | China Mainland Travel Permit for Taiwan Residents. |
00000001 | China Mainland 2nd-generation ID card. |
Response parameters
Field name | Data type | Description | Example | |
HTTP Status Code | Integer | The HTTP status code. | 200 | |
HTTP Body | RequestId | String | The unique ID of the request, which can be used to locate issues. | |
Code | String | Return code. For the full list of codes, see Codes and Messages. | Success | |
Message | String | Response detailed message. | success | |
Result.Passed | String | The final result of the identity verification. Possible values and their meanings are as below:
| Y | |
Result.SubCode | String | Authentication result sub code | 200 | |
Result.ExtFaceInfo | String | Detailed information about face verification. Optional. JSON string of ExtFaceInfo. For more information, see ExtFaceInfo showed below. |
| |
Result.ExtIdInfo | String | Detailed information about identity document recognition. Optional. JSON string of ExtIdInfo. For more information, see ExtIdInfo showed below. |
| |
Codes and Messages
HTTP Status Code | Code | Message |
200 | Success | The request has succeeded. |
400 | MissingParameter | The parameter is missing. |
400 | InvalidParameter | The parameter is invalid. |
400 | TransactionIdInvalid | Transaction id is invalid. |
403 | Forbidden.RAMUserAccessDenied | Grant AliyunAntCloudAuthFullAccess permission to the RAM user. For more information, see Authorize a RAM user to access ID Verification. |
403 | Forbidden.AccountAccessDenied | The account is unauthorized, overdue, deactivated, or disabled. |
403 | Throttling.Api | Request was denied due to api flow control. |
401 | UnqualifiedPhoto | The image is unreadable. Perhaps the resolution of the image does not meet the requirements. |
401 | ToolargeImage | The image is too large. |
401 | InvalidFormat | The format of the input name or ID number is invalid. |
401 | DataDuplication | Duplicate input parameters. We recommend that you choose only one of the picture formats. |
401 | DownloadTimeout | File download timed out. |
500 | InternalError | The error message returned when a temporary server error occurs. We recommend that you try again. If the error code persists, please submit a ticket for help. |
SubCode
SubCode | Whether billing | Message |
200 | Yes | pass. |
201 | Yes | Owner Name and ID number do not match in the authority database. The user information may be incorrect or false. You could suggest customer trying again. |
202 | Yes | No identity information can be found in the authority database. It is recommended to reserve manual review for this situation. |
203 | Yes | Unable to find or unavailable photos. Possible reason: The authoritative comparison source did not retain the bottom database photos. |
204 | Yes | The authentication failed. Similarity score is lower than threshold. Possible reasons: not the same person or the quality of the face selfie image is too low. |
205 | Yes | The authentication failed. Spoofing behavior is detected. |
207 | Yes | Face comparison with the authority database failed. Possible causes: not the same person or the quality of the face selfie image is too low. |
209 | Yes | Authority database exception. |
212 | Yes | The result of certificate anti-counterfeiting detection indicates tampering, screen recapture or photo copy are detected. |
ExtFaceInfo
The following table shows the fields that can be specified in the ExtFaceInfo data model.
Field name | Data type | Description | Example |
facePassed | String | The face result of the identity verification. Possible values and their meanings are as below:
| Y |
faceComparisonScore | Double | Specifies the score that indicates a result of comparing the live face (selfie) against the face recognized from the identity document. Required if the face verification process runs successfully. The value of this field is in the range of 0~100. | 99.99 |
faceAttack | String | Specifies whether the face selfie image is detected as a fake face attack by using the face liveness check algorithm. If the image is a fake face attack, the value of Y is returned; otherwise, the value of N is returned. | N |
authorityComparisonScore | Double | Specifies the score that indicates a result of comparing the live face (selfie) against the authority databases. Required if the value of Authorize is set to 'T'. | 99.99 |
ExtIdInfo
The following table shows the fields that can be specified in the ExtIdInfo data model.
Field name | Data type | Description | Example |
idPassed | String | Whether the identity document recognition process runs successfully. Valid values:
| N |
ocrIdInfo | String | Document OCR identification information, Json string, see the "OCR extraction field" column for details on the content format. Note If authentication or OCR fails, this parameter is left empty. |
|
spoofInfo | String | Spoofing check results of Identity document and corresponding types. Valid values:
|
|