Initialize - ID Verification - Alibaba Cloud Documentation Center

This topic describes how to call the Initialize operation to initiate an electronic Know Your Customer (eKYC) request.

Initiate a verification request

Operation name: Initialize.

Endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com.

Request method: HTTPS POST.

Operation description: Before you start a verification process, you must call this operation to obtain a transaction ID and transaction URL for different operations that are involved in the process.

Request parameters

Parameter	Type	Required	Description	Example
ProductCode	String	Yes	The solution that you want to use. Valid value: eKYC, which specifies the eKYC solution. If you use the eKYC solution, document recognition and face liveness verification are required for your customer.	eKYC
SceneCode	String	No	The ID of your custom verification scenario. You can enter the ID in the ID Verification console to query related records. You can specify a custom value that is 10 characters in length and contains letters, digits, and underscores (_).	1234567890
MerchantBizId	String	Yes	The unique identifier of your business, which is used for troubleshooting. You can specify a custom value that is 32 characters in length and contains letters and digits. Make sure that the value is unique. Note ID Verification does not check the uniqueness of the value. For tracing purposes, we recommend that you specify a unique value.	e0c34a77f5ac40a5aa5e6ed20c35****
MetaInfo	String	Yes	The environment parameters, which are obtained by using a client SDK. For more information, see Integrate the SDK for web with a PC or an HTML5 page. Note Specify the obtained parameters as environment parameters. You do not need to modify the parameters.	`{"zimVer":"3.0.0","appVersion": "1","bioMetaInfo": "4.1.0:1150****,0","appName": "com.aliyun.antcloudauth","deviceType": "h5","osVersion": "iOS 10.3.2","apdidToken": "","deviceModel": "iPhone9,1"}`
MerchantUserId	String	Yes	The ID of a customer. You can specify a custom value, such as a mobile phone number or an email address. Before you specify a value, we recommend that you perform data masking. For example, you can perform hashing.	123456789
IdSpoof	String	No	Specifies whether to enable anti-counterfeiting detection on documents. Valid values: Y N (default)	Y
ReturnUrl	String	Yes	The redirect URL of your business page.	https://www.alibabacloud.com
DocType	String	Yes	The document type. You can specify an 8-digit value to uniquely identify a document type. For more information, see the "Document types" section of this topic.	01000000
Authorize	String	No	Specifies whether to enable data verification against official data sources. Valid values: T F (default) Note Data verification against official data sources supports only second-generation ID cards for residents in the Chinese mainland.	F
LanguageConfig	String	No	The custom language configurations. Convert the language configurations that you want to add to a JSON string based on the configuration template. Then, specify this parameter to add the custom language configurations. For more information, see Add a language. Note This parameter is applicable only to integration by using the Web SDK mode. This parameter is not supported in integration by using PC pages.	{ "languageContent": {**}, "ocrResultContent": {}, "supportedLanguage": [], "titleTranslate": {**}, }
SecurityLevel	String	No	The mode for the different security levels of the verification process. Valid values: 01: the normal mode. This mode is applicable only to low-risk scenarios in which limits are imposed on device information collection. 02 (default): the secure mode, which is a strict mode. Note The secure mode allows you to use the face guard module added to the ID Verification SDK to check the security of the device that is used to collect face information based on the device information. This helps intercept injection attacks. We recommend that you select this mode.	02
StyleConfig	String	No	The custom UI configurations. Convert the UI configurations that you want to add to a JSON string based on the configuration template. Then, specify this parameter to add the custom UI configurations. For more information, see Custom UI configurations of ID Verification - KYC.	{ "guidepage:": {**}, "ocrPage": {}, "ocrResultPage": [], "facePage": {**}, }
IdThreshold	String	No	The threshold mode for the quality check of OCR. Valid values: 0: the default mode. 1: the strict mode. 2: the loose mode. 3: disables quality check.	0
Model	String	No	The type of liveness detection that you want to perform. Valid values: LIVENESS (default): blink-based detection. PHOTINUS_LIVENESS (recommended): blink-based plus color-based liveness detection. PHOTINUS_FAR_NEAR_LIVENESS: blink-based, near and far distance-based, plus color-based liveness detection. Note For more information about the SDK versions that can be integrated, see SDK release notes. Blink-based plus color-based liveness detection is not supported on PCs.	PHOTINUS_LIVENESS
DocVideo	String	No	Specifies whether to store the evidence video. Valid values: N (default): The video is not stored. Y: During the verification process, the video of the face verification process that lasts 1 to 2 seconds is collected and returned from the query operation. Note The system discards the video file when the network is unstable because the size of the video file is large. This ensures the stable transmission of images required for the verification. Videos cannot be returned from PCs.	N
ShowBlbumIcon	String	No	Specifies whether to display the entry for uploading a photo from the album during document optical character recognition (OCR). Valid values: 1 (default): yes. 0: no.	1
ShowOcrResult	String	No	Specifies whether to display the OCR result screen during document OCR. Valid values: 1 (default): yes. 0: no.	1

Document types

DocType	Document
01000000	Passports (Global)
00000006	ID cards (Hong Kong (China)) (2003 version)
00000008	ID cards (Hong Kong (China)) (2018 version)
00000007	Exit-entry Permit for Travelling to and from Hong Kong and Macao
00000009	Mainland Travel Permit for Hong Kong and Macao Residents
000000011	ID cards (Macao (China))
000000012	Mainland Travel Permit for Taiwan Residents
00000001	Second-generation ID cards for residents in the Chinese mainland

Response parameters

Parameter		Type	Description	Example
HTTP Status Code		Integer	The HTTP status code.	200
HTTP Body	RequestId	String	The request ID.	130A2C10-B9EE-4D84-88E3-5384FF039795
	Code	String	The code that is returned for the request. For more information, see HTTP status codes and messages.	success
	Message	String	The message that is returned for the request.	success
	Result.TransactionId	String	The unique identifier of the verification process. This parameter is used for billing. This parameter is also used to call the CheckResult operation. Note If an error occurred in the request, such as an invalid parameter, Result.TransactionId is not returned.	hksb7ba1b28130d24e015d694361bee4
	Result.TransactionUrl	String	The web verification URL. After the verification is complete, the page is redirected based on the value of the ReturnUrl parameter.	https://hkwebcdn.yuncloudauth.com/1.0.0/index.html?clientcfg=****

Codes and message descriptions

HTTP status code	Code	Message description
200	Success	The request is successful.
400	MissingParameter	A required parameter is empty.
400	InvalidParameter	A parameter is set to an invalid value.
403	Forbidden.RAMUserAccessDenied	The RAM user is not granted the required permission AliyunAntCloudAuthFullAccess. For more information, see Authorize a RAM user to access ID Verification - KYC.
403	Forbidden.AccountAccessDenied	The account has overdue payments. We recommend that you add funds to the account and try again.
403	Throttling.Api	API throttling is triggered.
404	ProcessNotCompleted	The verification process is not complete.
500	InternalError	An internal error occurred. To troubleshoot the error, we recommend that you submit your feedback to engineers.