Server-side integration - Captcha - Alibaba Cloud Documentation Center

After you complete the client-side integration, call the VerifyIntelligentCaptcha API from your server to complete the verification. This topic describes how to call the VerifyIntelligentCaptcha API.

Prerequisites

Create access credentials. The Captcha 2.0 server supports API calls that use various methods, such as an AccessKey or a Security Token Service (STS) token. For more information, see Initialize a credential client.

Important

Do not use the AccessKey of your Alibaba Cloud account. If your AccessKey is leaked, all your cloud resources are at risk. Use the AccessKey of a Resource Access Management (RAM) user to reduce security risks. To use Alibaba Cloud Captcha, grant the AliyunYundunAFSFullAccess permission to the RAM user.

Download and install the SDK

Download the server-side software development kit (SDK) package for your programming language from the OpenAPI Developer Portal. Captcha 2.0 provides server-side SDKs for Java, TypeScript, Go, PHP, Python, .NET, C++, and Swift.

Supported languages	SDK download address	GitHub source address
Java	Download Java SDK Download Java SDK (asynchronous)	Captcha SDK for Java Captcha SDK for Java-Async
Python	Download Python SDK	Captcha SDK for Python
TypeScript	Download TypeScript SDK	Captcha SDK for TypeScript
Go	Download Go SDK	Captcha SDK for Go
PHP	Download PHP SDK	Alibaba Cloud Green SDK for PHP
Swift	Download Swift SDK	Captcha SDK for Swift
C++	Download C++ SDK	Captcha SDK for C++
.NET	Download .NET SDK	Captcha SDK for .NET

Decompress the SDK package and load it into your server-side project.

Call the VerifyIntelligentCaptcha API

Send an authentication request

API name: VerifyIntelligentCaptcha

The value of the region parameter in AliyunCaptchaConfig must be correctly mapped to the server-side endpoint. Otherwise, the verification request returns an error.

Endpoint	Value of the region parameter for client-side integration	Corresponding server-side endpoint	Dual-stack support for the signature verification domain name
The Chinese mainland (Shanghai)	cn	IPv4: captcha.cn-shanghai.aliyuncs.com	Supports only IPv4
The Chinese mainland (Shanghai)	cn	Dual-stack: captcha-dualstack.cn-shanghai.aliyuncs.com	Supports both IPv4 and IPv6
Outside the Chinese mainland (Singapore)	sgp	IPv4: captcha.ap-southeast-1.aliyuncs.com	Supports only IPv4
Outside the Chinese mainland (Singapore)	sgp	Dual-stack: captcha-dualstack.ap-southeast-1.aliyuncs.com	Supports both IPv4 and IPv6

Request method: POST
Transport protocol: HTTPS
API description: Call this API from the server to perform verification after you configure the client-side Captcha.

Request parameters

Name	Type	Required	Description	Example
CaptchaVerifyParam	String	Yes	The verification parameter that is returned by the Captcha script callback. Pass all parameter information from the client to the server. Warning Do not modify the verification parameter. Otherwise, a business error occurs.	Example for V2 architecture: {"sceneId":"xxxxxx","certifyId":"xxxxxx","deviceToken":"xxxxxxx==","data":"xxxxxx==","..."} Example for V3 architecture: eyJjZXxxxxxxxxxxxxxxnVlfQ==
SceneId	String	No	The ID of the scenario for the current verification. Specify this parameter on your server, especially in multi-scenario deployments, to prevent the frontend from being tampered with to use other scenarios.	Udw***d72

Response parameters

Name			Type	Description
HTTP Status Code			Integer	The HTTP status code. For more information, see Description of response parameters.
HTTP Body	RequestId		String	The request ID.
	Success		Boolean	Indicates whether the request was successful. true: The request was successful. false: The request failed.
	Code		String	The return code. For more information, see Description of response parameters.
	Message		String	The detailed information. For more information, see Description of response parameters.
	Result	VerifyResult	Boolean	The verification result. true: The verification is passed. false: The verification failed.
		VerifyCode	String	T001	The server-side verification is passed.
				T005	Test mode is enabled in the console and configured to pass verifications. If you have questions, log on to the Captcha 2.0 console to view the policy status configuration for the scenario. For more information, see Integration guide.
				F001	A suspected attack request. The request is blocked by a risk control policy.
				F002	The `CaptchaVerifyParam` parameter that you passed is empty. `CaptchaVerifyParam` is automatically obtained by the frontend and passed to your server. Do not modify this parameter. Pass it directly to Alibaba Cloud. For more information, see Server-side integration to check your integration code.
				F003	The format of the `CaptchaVerifyParam` parameter that you passed is invalid. `CaptchaVerifyParam` is automatically obtained by the frontend and passed to your server. Do not modify this parameter. Pass it directly to Alibaba Cloud. For more information, see Server-side integration to check your integration code.
				F004	Test mode is enabled in the console and configured to block verifications. If you have questions, log on to the Captcha 2.0 console to view the policy status configuration for the scenario. For more information, see Manage scenarios.
				F005	The scene ID (sceneId) in CaptchaVerifyParam is invalid. CaptchaVerifyParam is automatically obtained by the frontend and passed to your server. Do not modify this parameter. Pass it directly to Alibaba Cloud. For more information, see Server-side integration to check your integration code.
				F006	The scene ID (sceneId) in `CaptchaVerifyParam` is invalid. The frontend integration must pass the scene ID that is created for your account. Log on to the Captcha 2.0 console to view the scenario configuration.
				F008	The verification data is submitted repeatedly. A verification code request can be submitted only once.
				F009	A virtual device environment is detected. Check whether you are using virtual machines such as VMware, VirtualBox, Hyper-V, or Parallels, emulators such as AVD, BlueStacks, or VBox/Hyper-V, or a desktop browser to impersonate a mobile device. If you do not want to block these requests, log on to the Captcha 2.0 console and disable this feature in the custom policy. For more information, see Set a custom policy.
				F010	The access frequency from the same IP address exceeds the limit. To customize the frequency threshold, log on to the Captcha 2.0 console and configure a custom policy. For more information, see Set a custom policy.
				F011	The access frequency from the same device exceeds the limit. To customize the frequency threshold, log on to the Captcha 2.0 console and configure a custom policy. For more information, see Set a custom policy.
				F012	The SceneID passed in your server-side parameters must be the same as the SceneId configured on the frontend.
				F013	The `CaptchaVerifyParam` parameter that you passed is missing parameters. `CaptchaVerifyParam` is automatically obtained by the frontend and passed to your server. Do not modify this parameter. Pass it directly to Alibaba Cloud. For more information, see Send an authentication request to check your integration code.
				F014	No initialization record is found. This may be due to two reasons: The interval between the verification request and the initialization request exceeds 20 minutes. The backend deletes the initialization record. Send the initialization request again. No initialization record exists. This may be a suspected attack request or an integration error. You must send a client-side initialization request before you send a verification request.
				F015	The verification interaction failed. For example, the puzzle piece was not moved to the correct position. You can refresh the Captcha and try again.
				F016	The request is blocked because of the URL verification configured in a custom policy in the console. Log on to the Captcha 2.0 console to adjust the URL verification policy. For more information, see Set a custom policy.
				F017	A suspected attack request. The request is blocked due to an abnormal protocol or parameter.
				F018	In the V3 architecture, the request parameter CaptchaVerifyParam for the business signature verification request is reused.
				F019	In the V3 architecture, the interval between the behavior verification request and the business signature verification request exceeds 90 seconds, or the business signature verification request is sent without a preceding behavior verification request.
				F020	In the V3 architecture, the CaptchaVerifyParam of the business signature verification request does not match the scene ID or user.
		CertifyID	String	If you pass the custom CertifyID parameter (UserCertifyId) during initialization, this value is passed through to support custom association and verification. If you do not pass a custom CertifyID parameter during initialization, this value is the default CertifyID generated by the server to identify a single verification epoch.

The following table describes the HTTP Status Code, Code, and Message response parameters.

HTTP Status Code	Code	Message
200	Success	The request is successful.
400	MissingParameter	A required parameter is missing.
401	InvalidParameter	The parameter is invalid.
403	Forbidden.AccountAccessDenied	You are not authorized to perform the operation. The service may not be activated, or your account may have an overdue payment.
403	Forbidden.RAMUserAccessDenied	The RAM user is not authorized to perform the operation. Grant the AliyunYundunAFSFullAccess permission to the RAM user. For more information, see Grant permissions to a RAM role.
500	InternalError	An internal error occurred. We recommend that you retry the request.

Code examples

Sample code for server-side intelligent verification