Get started

This guide will get you started on setting up the GoCaptcha.

Submit your domain

To start using GoCaptcha, you will need a secret and public key, which you will get after verifying your domain.

Client-side integration

The script below will give all functionality for the captcha to work. It will automatically import a css file for the captcha.

                    <script type="text/javascript" src="https://gocaptcha.net/static/scripts/api.js" defer></script>

Form Example

<!DOCTYPE html> 
<html> 
    <head> 
        <meta charset="utf-8"> 
        <title>Form Test - GoCaptcha</title> 
        <meta name="viewport" content="width=device-width, initial-scale=1" /> 
        <meta name="theme-color" content="#ffffff"> 
        <script type="text/javascript" src="https://gocaptcha.net/static/scripts/api.js" defer></script> 
    </head> 
    <body> 
        <form method="POST" action="/login"> 
            <input type="text" placeholder="username" required/> 
            <input type="password" placeholder="password" required/> 
            <button type="submit" gocaptcha="v1" sitekey="{public-key}">Login</button> 
        </form> 
    </body> 
</html>

An invisible input with the name gocaptcha-data is added and will be sent to the server with the other fields.

Required and Optional attributes

Key	Value	Required/Optional	Description
gocaptcha	v1	Required	This attribute will identify the object as a captcha, when clicked a captcha will be requested from our servers.
sitekey	{public-key}	Required	This public-key identifies your website, it is tied to the private-key that you will use on your server side.
ifsolved	{my-function}	Optional	ifsolved function will be executed when the captcha is successfuly solved. The function you pass takes data parameter that you must send to your server to verify the captcha.
clabel	Please complete the captcha to continue!	Optional	clabel will change the captcha title.

Request Example

If you want to make a request to send data to your server you must use the ifsolved attribute.

                    <!DOCTYPE html> 
<html> 
    <head> 
        <meta charset="utf-8"> 
        <title>Testing - GoCaptcha</title> 
        <meta name="viewport" content="width=device-width, initial-scale=1" /> 
        <meta name="theme-color" content="#ffffff"> 
        <script type="text/javascript" src="https://gocaptcha.net/static/scripts/api.js" defer></script> 
    </head> 
    <body> 
        <div> 
            <input type="text" id="username"> 
            <input type="password" id="password"> 
            <button type="button" gocaptcha="v1" sitekey="{public-key}" ifsolved="example">Login</button> 
        </div> 
        
        <script> 
            function example(data) { 
                const payload = {
                    "username": document.getElementById("username").value,
                    "password": document.getElementById("password").value,
                    "gocaptcha-data": data
                };
                
                const http = new XMLHttpRequest();
                http.open("POST", "https://example.com/login"); 
                http.send(JSON.stringify(payload)); 
            } 
        </script> 
    </body> 
</html>

If you are using a webframework that has a virtual DOM you must register the function on the DOM (React example below).

                    async function exampleFn() { 
    const resp = await fetch(process.env.REACT_APP_BASE_URL + "/login", 
    {method: "POST", body: JSON.stringify(form)});
    const data = await resp.json(); 
} 

useEffect(() => { 
    window.exampleFn = exampleFn; 
    window.GoCaptchaInit(); 
}, []); 

return ( 
<div> 
    <input type="text" id="username"> 
    <input type="password" id="password"> 
    <button gocaptcha="v1" sitekey="{public-key}" ifsolved="exampleFn">Login</button> 
</div> 
);

When you render a page you have to register your function in the window and call the GoCaptchaInit() to search for elements that have the attribute gocaptcha.

Server-side integration

On your server you must make a request to our servers to verify the data. The data may only be validated once. If the same data is presented twice, the second and each subsequent request will generate an error stating that the data has already been consumed.

Example using cURL:

                    curl https://gocaptcha.net/api/v1/siteverify?key={secret-key}&data=0e792878e84c...

Accepted parameters

Parameter	Required/Optional	Description
key	Required	Website identification
data	Required	Captcha identification
ip	Optional	User IP address. This feature prevents users from using 3rd party services to complete captchas for them.

In case of a successful validation, the response should be similar to the following:

                    {
    "status": "ok",
    "message": "Captcha valid!"
}

In case of a validation failure, the response should be similar to the following:

                    {
    "status": "error",
    "message": "Data corrupted!"
}

Error messages

Message	Description
Data not provided!	The url parameter data was not set.
Data corrupted!	Someone tried to manipulate the data to fake a captcha.
Captcha not found!	Meaning it was never created or already expired.
Captcha already verified!	If someone tries to fake a request by sending the same data, it will not work.
IP match failed!	We detected that some else has completed the captcha for the user.