Server-side integration-Captcha(Captcha)-阿里云帮助中心

After completing client-side integration, call the VerifyIntelligentCaptcha API from your server to validate each CAPTCHA challenge. Client-side verification alone does not protect your application — tokens can be forged by attackers and must be validated on your backend before you allow a request to proceed.

Prerequisites

Before you begin, make sure you have:

Completed client-side integration
Created access credentials — Captcha 2.0 supports AccessKey and Security Token Service (STS) token authentication. See Initialize a credential client
Granted the AliyunYundunAFSFullAccess permission to the Resource Access Management (RAM) user that calls the API

Important

Never use the AccessKey of your Alibaba Cloud root account. If it leaks, all your cloud resources are at risk. Use a RAM user's AccessKey instead.

How it works

Server-side verification follows this flow:

Client generates a token. The user completes the CAPTCHA challenge. The Captcha SDK produces a CaptchaVerifyParamCaptcha 2.0 console token and passes it to your server.
Your server calls `VerifyIntelligentCaptcha`. Send the token, unmodified, to the Captcha 2.0 service. Never alter CaptchaVerifyParam — any modification causes a verification error.
Captcha 2.0 responds. The API returns a VerifyResult (true or false) and a VerifyCode that describes the specific outcome.
Your server acts on the result. Allow the request if VerifyResult is true; reject it otherwise.

Token constraints:

Each token can only be verified once. Reuse returns F008.
The initialization record expires after 20 minutes. If the interval between initialization and verification exceeds 20 minutes, the token is invalid (F014).
In V3 architecture, the interval between the behavior verification request and the business signature verification request must not exceed 90 seconds (F019).

Install the SDK

Download the server-side SDK for your language from the OpenAPI Developer Portal. Decompress the package and load it into your project.

Language	Download	GitHub source
Java	Download	alibabacloud-java-sdk
Java (async)	Download	alibabacloud-java-async-sdk
Python	Download	alibabacloud-python-sdk
TypeScript	Download	alibabacloud-typescript-sdk
Go	Download	captcha-20230305
PHP	Download	alibabacloud-sdk-php
Swift	Download	alibabacloud-csharp-sdk
C++	Download	alibabacloud-sdk-cpp
.NET	Download	alibabacloud-csharp-sdk

Call the VerifyIntelligentCaptcha API

Send an authentication request

API name: VerifyIntelligentCaptcha

Ensure that the value of the region parameter in AliyunCaptchaConfig correctly maps to the server-side endpoint. An incorrect mapping causes the validation request to fail.

Service endpoint	Client region value	Corresponding server-side endpoint	Dual-stack support for signature verification domain
The Chinese mainland (Shanghai)	cn	IPv4: captcha.cn-shanghai.aliyuncs.com	Supports only IPv4
		Dual-stack: captcha-dualstack.cn-shanghai.aliyuncs.com	Supports both IPv4 and IPv6
		VPC: captcha-vpc.cn-shanghai.aliyuncs.com	Limited to cloud resources within a VPC in the Shanghai region
Outside the Chinese mainland (Singapore)	sgp	IPv4: captcha.ap-southeast-1.aliyuncs.com	Supports only IPv4
		Dual-stack: captcha-dualstack.ap-southeast-1.aliyuncs.com	Supports both IPv4 and IPv6
		VPC Network: captcha-vpc.ap-southeast-1.aliyuncs.com	Limited to cloud resources within a VPC in the Singapore region

Note

Conditions for calling the server-side Captcha API using a VPC domain name
To call the VerifyIntelligentCaptcha API using a VPC domain name, you must meet the following two conditions:

Deployment environment requirements: The service that sends the request must be deployed within an Alibaba Cloud virtual private cloud (VPC). Supported environments include cloud resources in the same VPC, such as Elastic Compute Service (ECS), Container Service for Kubernetes (ACK), and Function Compute. On-premises data centers or servers that are not on Alibaba Cloud cannot resolve VPC domain names and can connect only through public endpoints.
Region consistency requirements: The caller's region must match the VPC endpoint's region. VPC domain names do not support cross-region access. For example:
- Resources in the Shanghai region can use only captcha-vpc.cn-shanghai.aliyuncs.com.
- Resources in the Singapore region can use only captcha-vpc.ap-southeast-1.aliyuncs.com.

Advantages of VPC access

Bandwidth optimization: Requests are sent over the Alibaba Cloud internal network and do not use public bandwidth.
Performance improvement: Direct connections over the internal network reduce transmission delay.
Enhanced security: The internal network is isolated from the public internet, which improves data transmission security.

Request method: POST
Transport protocol: HTTPS
API description: After you configure the client-side Captcha, call this API on the server side to perform verification.

Request parameters

Parameter	Type	Required	Description
`CaptchaVerifyParam`	String	Yes	The token returned by the Captcha script callback. Pass it to the API exactly as received — do not modify it.
`SceneId`	String	No	The scenario ID for the current verification. Specify this on your server in multi-scenario deployments to prevent clients from substituting a different scenario.

CaptchaVerifyParam format by architecture:

V2: {"sceneId":"xxxxxx","certifyId":"xxxxxx","deviceToken":"xxxxxxx==","data":"xxxxxx==","..."}
V3: eyJjZXxxxxxxxxxxxxxxnVlfQ== (Base64-encoded)

Response parameters

Parameter	Type	Description
`RequestId`	String	The request ID.
`Success`	Boolean	`true` if the API call succeeded; `false` if it failed.
`Code`	String	The HTTP-level return code.
`Message`	String	Details about the return code.
`VerifyResult`	Boolean	`true` if the CAPTCHA challenge passed; `false` if it failed.
`VerifyCode`	String	The specific verification outcome code. See the table below.
`CertifyID`	String	The verification epoch identifier. If you passed a custom `UserCertifyId` during initialization, that value is returned here. Otherwise, the server generates a default `CertifyID`.

VerifyCode reference

Check VerifyResult first, then use VerifyCode for diagnostics and logging.

Code	Meaning	Action
T001	Verification passed.	Allow the request.
T005	Test mode is active and configured to pass all verifications.	In production, check the policy status in the Captcha 2.0 console. See Captcha 2.0 consoleIntegration guide.
F001	Suspected attack — blocked by the risk control policy.	Reject the request.
F002	`CaptchaVerifyParam` is empty.	Check your integration: the frontend must pass this parameter to your server without modification.
F003	`CaptchaVerifyParam` format is invalid.	Check your integration code — the parameter must not be altered before reaching the API.
F004	Test mode is active and configured to block all verifications.	Log on to the Captcha 2.0 console and adjust the policy status for this scenario. See Captcha 2.0 consoleManage scenarios.
F005	The `sceneId` in `CaptchaVerifyParam` is invalid.	Do not modify `CaptchaVerifyParam`. Check your integration code.
F006	The `sceneId` in `CaptchaVerifyParam` does not belong to your account.	Log on to the Captcha 2.0 console and verify the scenario configuration.
F008	Token reused — a token can only be submitted once.	Prompt the user to complete the CAPTCHA again to get a fresh token.
F009	Virtual device environment detected (VMware, VirtualBox, Hyper-V, Parallels, AVD, BlueStacks, or a desktop browser impersonating a mobile device).	Reject the request, or disable this check in the Captcha 2.0 console via a custom policy. See Captcha 2.0 consoleCaptcha 2.0 consoleCaptcha 2.0 consoleCaptcha 2.0 consoleSet a custom policy.
F010	Access frequency from the same IP address exceeds the limit.	Reject the request. Adjust the threshold in the Captcha 2.0 console if needed. See Set a custom policy.
F011	Access frequency from the same device exceeds the limit.	Reject the request. Adjust the threshold in the Captcha 2.0 console if needed. See Set a custom policy.
F012	The `SceneId` in your server-side request does not match the `sceneId` configured on the frontend.	Align your server-side `SceneId` with the scenario configured in the Captcha console.
F013	`CaptchaVerifyParam` is missing required fields.	Do not modify `CaptchaVerifyParam`. Check your integration code.
F014	No initialization record found.	Either the interval between initialization and verification exceeded 20 minutes (have the client reinitialize), or no initialization request was sent (check your client-side integration).
F015	Verification interaction failed (for example, the puzzle piece was not moved to the correct position).	Prompt the user to refresh the CAPTCHA and try again.
F016	Request blocked by the URL verification policy configured in the console.	Adjust the URL verification policy in the Captcha 2.0 console. See Set a custom policy.
F017	Suspected attack — blocked due to an abnormal protocol or parameter.	Reject the request.
F018	(V3 only) `CaptchaVerifyParam` for the business signature verification request is being reused.	Each business signature verification request must use a fresh token.
F019	(V3 only) The business signature verification request was sent more than 90 seconds after the behavior verification request, or without a preceding behavior verification request.	Make sure the business signature verification request follows the behavior verification request within 90 seconds.
F020	(V3 only) The `CaptchaVerifyParam` of the business signature verification request does not match the scene ID or user.	Check that the token used for business signature verification corresponds to the correct scene and user.

HTTP status codes

HTTP status	Code	Message
200	`Success`	The request is successful.
400	`MissingParameter`	A required parameter is missing.
401	`InvalidParameter`	The parameter is invalid.
403	`Forbidden.AccountAccessDenied`	Not authorized. The service may not be activated, or your account has an overdue payment.
403	`Forbidden.RAMUserAccessDenied`	The RAM user is not authorized. Grant the AliyunYundunAFSFullAccess permission. See Grant permissions to a RAM role.
500	`InternalError`	An internal error occurred. Retry the request.

Code examples

For complete, runnable server-side verification examples in all supported languages, see Sample code for server-side intelligent verification on the OpenAPI Developer Portal.

What's next

Manage scenarios — create and configure scenarios for different verification contexts
Set a custom policy — adjust frequency limits, virtual device detection, and URL verification rules