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
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(trueorfalse) and aVerifyCodethat describes the specific outcome.Your server acts on the result. Allow the request if
VerifyResultistrue; 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 | SDK download url | Github source url |
Java | ||
Python | ||
TypeScript | ||
Go | ||
PHP | ||
Swift | ||
C++ | ||
.NET |
Call the VerifyIntelligentCaptcha API
Choose an endpoint
Map the region value from your client-side AliyunCaptchaConfig to the correct server-side endpoint. Mismatched regions cause request errors.
Client region value | Deployment | Server-side endpoint |
|---|---|---|
cn | The Chinese mainland (Shanghai) — IPv4 only | captcha.cn-shanghai.aliyuncs.com |
cn | The Chinese mainland (Shanghai) — dual-stack (IPv4 and IPv6) | captcha-dualstack.cn-shanghai.aliyuncs.com |
sgp | Outside the Chinese mainland (Singapore) — IPv4 only | captcha.ap-southeast-1.aliyuncs.com |
sgp | Outside the Chinese mainland (Singapore) — dual-stack (IPv4 and IPv6) | captcha-dualstack.ap-southeast-1.aliyuncs.com |
The API uses HTTPS and POST.
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