Welcome to xCaptcha Documentation

Introduction

xCaptcha is a powerful and user-friendly captcha service designed to protect your online forms and websites from automated bots. With a focus on security, accessibility, and ease of integration, xCaptcha offers a reliable solution to prevent spam and abuse.

You integrate the Xcaptcha widget into your website, such as within a login form. After completing an Xcaptcha challenge, the user receives a passcode generated by our server, which is then embedded into your form. When the user submits the form, the passcode is transmitted to your server. Your server then verifies the passcode using the Xcaptcha server API. Once Xcaptcha confirms the passcode's validity, your server acknowledges that the user is not a bot and proceeds to allow them to log in. It's a straightforward and effective method!

Sign Up

To start using xCaptcha, sign up for an account on our website.
Once registered, you'll be able to access your dashboard and obtain API keys.

API Key

Retrieve your API key from the dashboard.
The API key is essential for integrating xCaptcha into your forms and verifying captcha responses.

Installation

xCaptcha can be easily integrated into your website or application using the following steps

Add the xCaptcha Widget to your Webpage

Add the following HTML code inside your form where you want the captcha to appear:

<div id="__xCaptchaDiv" data-sitekey="SITE_KEY" style="min-height:75px!important"></div>
<script src="https://static.xcaptcha.com/js/api.js"></script>

* Replace the SITE_KEY with your Site Key

Server-side

Validate the captcha response on your server using your preferred programming language.
Examples:

            $url = 'https://api.xcaptcha.com/verify/{SITE_KEY}';
$headers = array(
    "w-private-key: {YOUR-PRIVATE-KEY}", //Private Key
    "w-response: {XCAPTCHA_RESPONSE}",
    "w-ip: {IP}", //optional
    "w-user-agent: {USER_AGENT}", //optional
    "w-http-accept: {HTTP_ACCEPT}", //optional
    "w-language: {LANGUAGE}", //optional
    "w-referer: {REFERER}" //optional
);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$response = json_decode(curl_exec($curl));
curl_close($curl);

if (!isset($res->success)) {
    //An error occurred
} else if ($res->success) {
   //success
} else {
   //fail
}import requests

url = 'https://api.xcaptcha.com/verify/{SITE_KEY}'
headers = {
    "w-private-key": "{YOUR-PRIVATE-KEY}", 
    "w-response": "{XCAPTCHA_RESPONSE}",
    "w-ip": "{IP}",                   
    "w-user-agent": "{USER_AGENT}",   
    "w-http-accept": "{HTTP_ACCEPT}", 
    "w-language": "{LANGUAGE}",       
    "w-referer": "{REFERER}"          
}

response = requests.get(url, headers=headers)
data = response.json()

if 'success' not in data:
    # An error occurred
    pass
elif data['success']:
    # Success
    pass
else:
    # Fail
    pass
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.xcaptcha.com/verify/{SITE_KEY}"
	headers := map[string]string{
		"w-private-key":   "{YOUR-PRIVATE-KEY}",
		"w-response":      "{XCAPTCHA_RESPONSE}",
		"w-ip":            "{IP}",              // optional
		"w-user-agent":    "{USER_AGENT}",      // optional
		"w-http-accept":   "{HTTP_ACCEPT}",     // optional
		"w-language":      "{LANGUAGE}",        // optional
		"w-referer":       "{REFERER}",         // optional
	}

	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	for key, value := range headers {
		req.Header.Set(key, value)
	}

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer resp.Body.Close()

	var response map[string]interface{}
	err = json.NewDecoder(resp.Body).Decode(&response)
	if err != nil {
		fmt.Println("Error decoding response:", err)
		return
	}

	// Check success
	if _, ok := response["success"]; !ok {
		// An error occurred
	} else if success, ok := response["success"].(bool); ok {
		if success {
			// Success
		} else {
			// Fail
		}
	} else {
		// Invalid response format
	}
}
const https = require('https');

const url = 'https://api.xcaptcha.com/verify/{SITE_KEY}';
const headers = {
    "w-private-key": "{YOUR-PRIVATE-KEY}",
    "w-response": "{XCAPTCHA_RESPONSE}",
    "w-ip": "{IP}",                  // optional
    "w-user-agent": "{USER_AGENT}",  // optional
    "w-http-accept": "{HTTP_ACCEPT}",// optional
    "w-language": "{LANGUAGE}",      // optional
    "w-referer": "{REFERER}"         // optional
};

const options = {
    method: 'GET',
    headers: headers
};

const req = https.request(url, options, (res) => {
    let data = '';
    res.on('data', (chunk) => {
        data += chunk;
    });

    res.on('end', () => {
        const response = JSON.parse(data);
        if ('success' in response) {
            if (response.success) {
                // success
            } else {
                // fail
            }
        } else {
            // An error occurred
        }
    });
});

req.on('error', (error) => {
    console.error('Error sending request:', error);
});

req.end();
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Map;
import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        try {
            String url = "https://api.xcaptcha.com/verify/{SITE_KEY}";

            Map headers = new HashMap<>();
            headers.put("w-private-key", "{YOUR-PRIVATE-KEY}");
            headers.put("w-response", "{XCAPTCHA_RESPONSE}");
            headers.put("w-ip", "{IP}");                     // optional
            headers.put("w-user-agent", "{USER_AGENT}");     // optional
            headers.put("w-http-accept", "{HTTP_ACCEPT}");   // optional
            headers.put("w-language", "{LANGUAGE}");         // optional
            headers.put("w-referer", "{REFERER}");           // optional

            URL obj = new URL(url);
            HttpURLConnection con = (HttpURLConnection) obj.openConnection();

            // Set request method
            con.setRequestMethod("GET");

            // Set request headers
            for (Map.Entry entry : headers.entrySet()) {
                con.setRequestProperty(entry.getKey(), entry.getValue());
            }

            int responseCode = con.getResponseCode();
            System.out.println("Response Code: " + responseCode);

            BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
            String inputLine;
            StringBuffer response = new StringBuffer();

            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();

            // Convert response to JSON format
            String jsonResponse = response.toString();
            System.out.println("Response: " + jsonResponse);

            // Parse JSON response
            // Implement logic to check success or failure
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
#!/bin/bash

url="https://api.xcaptcha.com/verify/{SITE_KEY}"
private_key="{YOUR-PRIVATE-KEY}"
response="{XCAPTCHA_RESPONSE}"
ip="{IP}"                      # optional
user_agent="{USER_AGENT}"      # optional
http_accept="{HTTP_ACCEPT}"    # optional
language="{LANGUAGE}"          # optional
referer="{REFERER}"            # optional

curl -X GET "$url" \
    -H "w-private-key: $private_key" \
    -H "w-response: $response" \
    -H "w-ip: $ip" \
    -H "w-user-agent: $user_agent" \
    -H "w-http-accept: $http_accept" \
    -H "w-language: $language" \
    -H "w-referer: $referer"

* Replace values with yours:

This script sends a POST request to the XCAPTCHA API endpoint for verification, including the necessary headers. Make sure to handle the response appropriately.

Upon making a POST request, your application will receive a response in JSON format. It's crucial to examine the 'success' field within this response. If the 'success' field is true, proceed with your standard business logic. However, if 'success' is false, scrutinize the 'error-codes' field for a human-readable error code. In case of an error, provide the end user with an error message that corresponds to the identified issue. If the 'error-codes' field doesn't contain specific details, present a generic error message to the user. This ensures a user-friendly experience by offering clear feedback based on the outcome of the captcha verification.

Errors by HTTP status:

Configuration Options

Language

By default, the widget language is set automatically based on the device settings. However, you have the option to manually configure the widget language if you prefer with the data-lang attribute:.

<div id="__xCaptchaDiv" data-lang="LANGUAGE" data-sitekey="SITE_KEY">

Available languages:

Invisible Captcha

You can hide the captcha widget by adding display:none to the style, and then initialize it through JavaScript.

Javascript functions

Custom Challenges

Create custom challenges for enhanced security and user engagement.

Secure Communication

Always use SSL/TLS for secure communication between your server and xCaptcha to prevent man-in-the-middle attacks.

Support

For issues or inquiries, contact our support team.
Thank you for choosing xCaptcha to protect your online forms and websites!