The server-side verification process is also simple and straightforward. To ensure security, you must always validate the CAPTCHA response on your backend before processing any form submission.
We provide sample implementations in multiple programming languages to help you get started quickly.
Follow the steps below to complete the integration:
Server-side verification is required to ensure the CAPTCHA response is valid and not forged. This step should always be performed on your backend before processing any form submission.
Below is a simple PHP implementation you can copy or adapt into your project.
Create a reusable class (e.g. C3Captcha) to handle verification requests:
<?php
namespace App\Util;
use camilord\utilus\Net\Qurl;
class C3Captcha
{
const BASE_URL = 'https://captcha.camilord.com';
private ?string $error_message;
public function __construct(
private string $secret_key
) { }
public function getErrorMessage(): ?string {
return $this->error_message;
}
public function verify($inpur_response)
{
$url = self::BASE_URL.'/v1/verify';
$response = Qurl::post($url, [
'secret_key' => $this->secret_key,
'response_token' => $inpur_response,
]);
$this->error_message = $response['message'] ?? null;
return (($response['success'] ?? false) === true);
}
};When processing your form submission, retrieve the CAPTCHA response from POST data and validate it using your class:
<?php
use App\Util\C3Captcha;
$c3_captcha_response = $_POST['c3-captcha-response'] ?? null;
$captcha = new C3Captcha($_ENV['CAPTCHA_SECRET_KEY'])
if (!$captch->verify($c3_captcha_response)) {
echo $captcha->getErrorMessage(); // error, validation incorrect or failed
} else {
// next process
}
c3-captcha-response token is sent with the formOnce integrated, your form is protected against automated submissions and bot attacks with minimal setup and no additional complexity.
Create a file: app/services/c3_captcha.rb
require 'net/http'
require 'uri'
require 'json'
class C3Captcha
BASE_URL = 'https://captcha.camilord.com'
def initialize(secret_key)
@secret_key = secret_key
@error_message = nil
end
def error_message
@error_message
end
def verify(response_token)
url = URI.parse("#{BASE_URL}/v1/verify")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url.path, {
'Content-Type' => 'application/json'
})
request.body = {
secret_key: @secret_key,
response_token: response_token
}.to_json
response = http.request(request)
result = JSON.parse(response.body) rescue {}
@error_message = result['message']
result['success'] == true
end
end
Example inside a controller handling form submission:
def create
captcha_response = params['c3-captcha-response']
captcha = C3Captcha.new(ENV['CAPTCHA_SECRET_KEY'])
unless captcha.verify(captcha_response)
render plain: captcha.error_message, status: :unprocessable_entity
return
end
# CAPTCHA passed — continue processing
# your logic here
end
Create a file: c3captcha.py
import requests
class C3Captcha:
BASE_URL = "https://captcha.camilord.com"
def __init__(self, secret_key: str):
self.secret_key = secret_key
self._error_message = None
def get_error_message(self):
return self._error_message
def verify(self, response_token: str) -> bool:
url = f"{self.BASE_URL}/v1/verify"
payload = {
"secret_key": self.secret_key,
"response_token": response_token
}
try:
response = requests.post(url, json=payload, timeout=10)
result = response.json()
except Exception as e:
self._error_message = str(e)
return False
self._error_message = result.get("message")
return result.get("success", False) is True
Example in a generic Python backend:
from c3captcha import C3Captcha
import os
def handle_form(request):
captcha_response = request.form.get("c3-captcha-response")
captcha = C3Captcha(os.getenv("CAPTCHA_SECRET_KEY"))
if not captcha.verify(captcha_response):
return {
"error": captcha.get_error_message()
}, 400
# CAPTCHA passed
return {
"success": True
}
Create a file: /Services/C3Captcha.cs
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
public class C3Captcha
{
private const string BASE_URL = "https://captcha.camilord.com";
private readonly string _secretKey;
private string? _errorMessage;
private static readonly HttpClient _httpClient = new HttpClient();
public C3Captcha(string secretKey)
{
_secretKey = secretKey;
}
public string? GetErrorMessage()
{
return _errorMessage;
}
public async Task VerifyAsync(string responseToken)
{
var url = $"{BASE_URL}/v1/verify";
var payload = new
{
secret_key = _secretKey,
response_token = responseToken
};
var json = JsonSerializer.Serialize(payload);
var request = new HttpRequestMessage(HttpMethod.Post, url)
{
Content = new StringContent(json, Encoding.UTF8, "application/json")
};
try
{
var response = await _httpClient.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
var result = JsonSerializer.Deserialize(responseBody);
_errorMessage = result?.message;
return result?.success == true;
}
catch (Exception ex)
{
_errorMessage = ex.Message;
return false;
}
}
private class C3CaptchaResponse
{
public bool success { get; set; }
public string? message { get; set; }
}
}
Example (MVC / API Controller)
[HttpPost]
public async Task SubmitForm(IFormCollection form)
{
var captchaResponse = form["c3-captcha-response"];
var captcha = new C3Captcha(Environment.GetEnvironmentVariable("CAPTCHA_SECRET_KEY"));
if (!await captcha.VerifyAsync(captchaResponse))
{
return BadRequest(captcha.GetErrorMessage());
}
// CAPTCHA passed — continue processing
return Ok(new { success = true });
}
Create a file: c3captcha.ts
import fetch from "node-fetch";
export class C3Captcha {
private static readonly BASE_URL = "https://captcha.camilord.com";
private secretKey: string;
private errorMessage: string | null = null;
constructor(secretKey: string) {
this.secretKey = secretKey;
}
public getErrorMessage(): string | null {
return this.errorMessage;
}
public async verify(responseToken: string): Promise {
const url = `${C3Captcha.BASE_URL}/v1/verify`;
try {
const res = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
secret_key: this.secretKey,
response_token: responseToken
})
});
const result = await res.json();
this.errorMessage = result?.message ?? null;
return result?.success === true;
} catch (err: any) {
this.errorMessage = err.message ?? "Unknown error";
return false;
}
}
}
import express from "express";
import { C3Captcha } from "./c3captcha";
const app = express();
app.use(express.json());
app.post("/submit", async (req, res) => {
const captchaResponse = req.body["c3-captcha-response"];
const captcha = new C3Captcha(process.env.CAPTCHA_SECRET_KEY as string);
const valid = await captcha.verify(captchaResponse);
if (!valid) {
return res.status(400).json({
error: captcha.getErrorMessage()
});
}
// CAPTCHA passed
return res.json({ success: true });
});
app.listen(3000, () => console.log("Server running"));
Create a file: C3Captcha.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
public class C3Captcha {
private static final String BASE_URL = "https://captcha.camilord.com";
private final String secretKey;
private String errorMessage;
private final HttpClient httpClient;
private final ObjectMapper objectMapper;
public C3Captcha(String secretKey) {
this.secretKey = secretKey;
this.httpClient = HttpClient.newHttpClient();
this.objectMapper = new ObjectMapper();
}
public String getErrorMessage() {
return errorMessage;
}
public boolean verify(String responseToken) {
try {
String url = BASE_URL + "/v1/verify";
String jsonBody = objectMapper.writeValueAsString(new Payload(secretKey, responseToken));
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
JsonNode result = objectMapper.readTree(response.body());
errorMessage = result.has("message") ? result.get("message").asText() : null;
return result.has("success") && result.get("success").asBoolean(false);
} catch (Exception e) {
errorMessage = e.getMessage();
return false;
}
}
// Inner payload class
private static class Payload {
public String secret_key;
public String response_token;
public Payload(String secretKey, String responseToken) {
this.secret_key = secretKey;
this.response_token = responseToken;
}
}
}
Example in a controller:
@PostMapping("/submit")
public ResponseEntity submit(@RequestParam("c3-captcha-response") String captchaResponse) {
C3Captcha captcha = new C3Captcha(System.getenv("CAPTCHA_SECRET_KEY"));
if (!captcha.verify(captchaResponse)) {
return ResponseEntity
.badRequest()
.body(captcha.getErrorMessage());
}
// CAPTCHA passed — continue processing
return ResponseEntity.ok("success");
}
Create a file: c3captcha.go
package c3captcha
import (
"bytes"
"encoding/json"
"errors"
"io"
"net/http"
"time"
)
const BASE_URL = "https://captcha.camilord.com"
type C3Captcha struct {
secretKey string
errorMessage string
httpClient *http.Client
}
type verifyRequest struct {
SecretKey string `json:"secret_key"`
ResponseToken string `json:"response_token"`
}
type verifyResponse struct {
Success bool `json:"success"`
Message string `json:"message"`
}
func NewC3Captcha(secretKey string) *C3Captcha {
return &C3Captcha{
secretKey: secretKey,
httpClient: &http.Client{
Timeout: 10 * time.Second,
},
}
}
func (c *C3Captcha) GetErrorMessage() string {
return c.errorMessage
}
func (c *C3Captcha) Verify(responseToken string) bool {
url := BASE_URL + "/v1/verify"
payload := verifyRequest{
SecretKey: c.secretKey,
ResponseToken: responseToken,
}
jsonData, err := json.Marshal(payload)
if err != nil {
c.errorMessage = err.Error()
return false
}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
if err != nil {
c.errorMessage = err.Error()
return false
}
req.Header.Set("Content-Type", "application/json")
resp, err := c.httpClient.Do(req)
if err != nil {
c.errorMessage = err.Error()
return false
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
c.errorMessage = err.Error()
return false
}
var result verifyResponse
if err := json.Unmarshal(body, &result); err != nil {
c.errorMessage = err.Error()
return false
}
c.errorMessage = result.Message
return result.Success
}
In a Go handler (net/http)
package main
import (
"fmt"
"net/http"
"os"
"yourmodule/c3captcha"
)
func handler(w http.ResponseWriter, r *http.Request) {
r.ParseForm()
captchaResponse := r.FormValue("c3-captcha-response")
captcha := c3captcha.NewC3Captcha(os.Getenv("CAPTCHA_SECRET_KEY"))
if !captcha.Verify(captchaResponse) {
http.Error(w, captcha.GetErrorMessage(), http.StatusBadRequest)
return
}
fmt.Fprintln(w, "success")
}
func main() {
http.HandleFunc("/submit", handler)
http.ListenAndServe(":8080", nil)
}
Message here...
Modal body text goes here.
Modal body text goes here.
Modal body text goes here.