CAPTCHA Integration Guide

This guide explains how to integrate the browser challenge CAPTCHA into your own website to protect against bots and automated abuse.

Client-Side Integration

1. Add the Challenge Script

Include the main challenge script in your HTML page. It is recommended to place this in the <head> with the defer attribute or at the end of the <body>.

<script src="https://challenge.xewdy.systems/static/js/main.js" defer></script>

You can also add the following links to your <head> to improve performance:

<link rel="preconnect" href="https://challenge.xewdy.systems" crossorigin>
<link rel="dns-prefetch" href="//challenge.xewdy.systems">

2. Add the Challenge Container

Add a div element with the ID challenge-container where you want the CAPTCHA widget to appear.

<div id="challenge-container"></div>

Customization Options

You can customize the appearance of the CAPTCHA widget using data attributes on the challenge-container element.

data-color: Sets the background color of the widget.
data-text-color: Sets the text color of the widget.

Both of these accept any valid CSS color value (e.g., hex, rgb, color name).

<div id="challenge-container" data-color="#2a2a2a" data-text-color="#ffffff"></div>

3. Handling the Passage Token

When the user successfully passes the challenge, the script provides a passage token. By default, the script will create a hidden input field named passage_token inside the challenge container and set its value to the token.

You can optionally define your own input element to receive the token by giving it the ID passage-token. This is useful if you want to integrate it into an existing form structure.

<input type="hidden" id="passage-token" name="my_custom_token_name">

4. Client-Side Callbacks

You can optionally define a global onChallengeComplete function to handle challenge results programmatically.

window.onChallengeComplete = function(success, token, error, errorCode) {
  if (success) {
    console.log(`Challenge passed! Passage token: ${token}`);
  } else {
    console.error(`Challenge failed. Error: ${error} (Code: ${errorCode})`);
  }
};

The function can also be asynchronous if you need to perform async operations.

Server-Side Verification

Once the user submits the form with the passage token, you need to verify it on your server by making an API call to the verification endpoint.

API Endpoint

POST https://challenge.xewdy.systems/capi/captcha/verify-token

Request Payload

Send a JSON object with the following fields:

Field Name	Required	Description
`passage_token`	Yes	The token received from the client.
`ip_address`	No	The IP address of the user. It's usually not recommended to provide this unless you need very strict verification.
`user_agent`	No	The User-Agent string of the user's browser. It's recommended to include this for better verification.

Example Request

{
  "passage_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
}

Response

The API returns a JSON response indicating whether the verification was successful.

Success Response (200 OK):

{
  "success": true
}

Error Response (400 Bad Request):

{
  "code": 322,
  "error": "Invalid or expired passage token",
  "success": false
}

Possible Error Codes

Code	Message
62660	IP address mismatch
28685	Duplicate passage token
14260	User agent mismatch
322	Invalid or expired passage token
259	Internal server error