DocsICP FilingConsole
官方文档
首页

Server-side integration

更新时间：
复制 MD 格式
我的收藏

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:

  1. 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.

  2. Your server calls `VerifyIntelligentCaptcha`. Send the token, unmodified, to the Captcha 2.0 service. Never alter CaptchaVerifyParam — any modification causes a verification error.

  3. Captcha 2.0 responds. The API returns a VerifyResult (true or false) and a VerifyCode that describes the specific outcome.

  4. 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

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

Previous：V3 client architecture response dataNext：Style management