Verifying a CAPTCHA response
After validating a request, SmartCaptcha assigns it an ID: a one-time token. You can use the token to retrieve the result of a user request validation from the service. The token is valid for five minutes. After this time expires, it becomes invalid and the user has to go through the validation process again.
After validation, the token is inserted into the <input type="hidden" name="smart-token" value="<token>" ...>
element on the user page, For example:
<div id="captcha-container" class="smart-captcha" ...>
<input type="hidden" name="smart-token" value="dD0xNjYyNDU3NDMzO2k9MmEwMjo2Yjg6YjA4MTpiNTk3OjoxOjFiO0Q9MjVCREY1RDgzMDBERjQ3QjExNkUyMDJDNjJFNEI3Q0Y0QjYzRkRDNzJEMkV********DNjMxODgzMUM0REZBNzI1QUE1QzUwO3U9MTY2MjQ1NzQzMzk5MTEwNjQxNTtoPTg4MWRjMDc2YzE3MjkxNGUwNDgwMTVkYzhl********">
...
</div>
Where:
<div id="captcha-container" class="smart-captcha" ...>
:div
element with the widget.value
: Token value.
To retrieve a validation result, send a GET request containing the token to https://smartcaptcha.yandexcloud.net/validate
:
https://smartcaptcha.yandexcloud.net/validate?secret=<server_key>&ip=<user_IP>&token=<token>
Where:
secret
: Server key.token
: One-time token received after passing the check.ip
: IP address of the user that originated the request to validate the token. This is an optional parameter, but we ask you to provide the user IP when making requests. This helps improve SmartCaptcha performance.
Service response
In its response, the service will return a JSON object containing the status
and the message
fields. If the status
field value is ok
, the host
field is added to a JSON object. It shows on what website the validation was passed. For example:
-
It is a human. User validation was passed on the
example.com
website:{ "status": "ok", "message": "", "host": "example.com" }
-
It is a human. User validation was passed on the
example.com
website through port8080
:{ "status": "ok", "message": "", "host": "example.com:8080" }
-
Empty
host
field. This may indicate that the cloud is blocked or an internal service failure occurred:{ "status": "ok", "message": "", "host": "" }
-
It is a robot:
{ "status": "failed", "message": "" }
-
Request with a fake or damaged token. It is a robot:
{ "status": "failed", "message": "Token invalid or expired." }
Request errors
If your request to https://smartcaptcha.yandexcloud.net/validate
is incorrect, the service will return an error. For example:
-
Request missing the server key:
{ "status": "failed", "message": "Authentication failed. Secret has not provided." }
-
Request with a missing or damaged token:
{ "status": "failed", "message": "Token invalid or expired." }
Note
To avoid delays when processing user requests, we recommend processing HTTP errors (response codes other than 200) as the "status": "ok"
server response.