Verify powCAPTCHA response

To verify the powCAPTCHA response on your server, you need to send a POST request to the powCAPTCHA verification endpoint with the necessary parameters. Here’s how you can do it:

Endpoint

Section titled Endpoint

The verification endpoint URL is:

https://api.powcaptcha.com/challenges/verify

Request Method

Section titled Request Method

The request method is POST.

Request Headers

Section titled Request Headers

Content-Type: application/json

Request Body

Section titled Request Body

{
  "solution": "your_solution_token",
  "secret": "your_private_key",
  "spamFilter": {
    "text": "optional_text_to_check_for_spam",
    "email": "optional_email_to_check_for_spam"
  }
}

Parameters

Section titled Parameters

Parameter	Type	Description
solution	string	The solution token received from the powCAPTCHA widget.
secret	string	Your application’s private key (keep this secret, do not expose on the frontend).
spamFilter	object	(Optional) Object with optional text and/or email fields for spam filtering. Requires paid plan for advanced filtering.
spamFilter.text	string	(Optional) Text to check for spam (requires paid plan for advanced filtering).
spamFilter.email	string	(Optional) Email to check for spam (requires paid plan for advanced filtering).

Server-side Verification Examples

Section titled Server-side Verification Examples

Below are examples of how to verify the powCAPTCHA response on your server using various programming languages.

JavaScript

const url = 'https://api.powcaptcha.com/challenges/verify';
const solution = 'received_solution_token_from_frontend';
const secret = 'your_powcaptcha_secret_key';
const payload = { solution, secret };
// if you are a premium user, you can pass the `spamFilter` parameter to filter spam
/* payload.spamFilter = {
	email: requestUser.email,
	text: requestUser.text, // text from the user action, e.g. comment, post, etc.
} */

const res = await fetch(url, {
	method: 'POST',
	headers: { 'Content-Type': 'application/json' },
	body: JSON.stringify(payload),
});
const response = await res.json();
if (response.success) {
	// CAPTCHA verification successful
	const signals = response.data.signals;
	console.log('Signals score:', signals.score);
	// if you are a premium user and you passed the `spamFilter` parameter, you can use it to filter spam
	const spamFilter = response.data.spamFilter;
	console.log('Spam filter score:', spamFilter.score);

	// after here you can decide whether to proceed with the user action or block it depending on the scores
	// for example:
	if (signals.score < 0.5) {
		// signals is not acceptable, block the user action
		console.log('Block user action due to low signals score:', signals.score);
		return;
	}
	if (spamFilter && spamFilter.score < 0.5) {
		// spam filter is not acceptable, block the user action
		console.log('Block user action due to low spam filter score:', spamFilter.score);
		return;
	}

	console.log('Proceed with user action.');
} else {
	console.log('Block user action due to CAPTCHA failure:', response.error || 'Verification failed');
}

PHP

<?php

$url = 'https://api.powcaptcha.com/challenges/verify';
$solution = 'received_solution_token_from_frontend';
$secret = 'your_powcaptcha_secret_key';

$payload = [
	'solution' => $solution,
	'secret' => $secret,
];

// If you are a premium user, you can pass the `spamFilter` parameter to filter spam
/*
$payload['spamFilter'] = [
	'email' => $requestUser['email'],
	'text' => $requestUser['text'], // text from the user action, e.g. comment, post, etc.
];
*/

$options = [
	'http' => [
		'header'  => "Content-Type: application/json\r\n",
		'method'  => 'POST',
		'content' => json_encode($payload),
		'ignore_errors' => true,
	],
];

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);

if ($result === FALSE) {
	// Handle error
	echo "Block user action due to CAPTCHA failure: Request failed";
	return;
}

$response = json_decode($result, true);

if (!empty($response['success'])) {
	// CAPTCHA verification successful
	$signals = $response['data']['signals'];
	echo 'Signals score: ' . $signals['score'] . PHP_EOL;

	// If you are a premium user and you passed the `spamFilter` parameter, you can use it to filter spam
	$spamFilter = isset($response['data']['spamFilter']) ? $response['data']['spamFilter'] : null;
	if ($spamFilter) {
		echo 'Spam filter score: ' . $spamFilter['score'] . PHP_EOL;
	}

	// Decide whether to proceed with the user action or block it depending on the scores
	if ($signals['score'] < 0.5) {
		echo 'Block user action due to low signals score: ' . $signals['score'] . PHP_EOL;
		return;
	}
	if ($spamFilter && $spamFilter['score'] < 0.5) {
		echo 'Block user action due to low spam filter score: ' . $spamFilter['score'] . PHP_EOL;
		return;
	}

	echo 'Proceed with user action.' . PHP_EOL;
} else {
	$error = isset($response['error']) ? $response['error'] : 'Verification failed';
	echo 'Block user action due to CAPTCHA failure: ' . $error . PHP_EOL;
}

Python

import requests
import json

url = 'https://api.powcaptcha.com/challenges/verify'
solution = 'received_solution_token_from_frontend'
secret = 'your_powcaptcha_secret_key'

payload = {
	'solution': solution,
	'secret': secret,
}

# If you are a premium user, you can pass the `spamFilter` parameter to filter spam
# payload['spamFilter'] = {
#     'email': request_user['email'],
#     'text': request_user['text'],  # text from the user action, e.g. comment, post, etc.
# }

headers = {
	'Content-Type': 'application/json'
}

try:
	response = requests.post(url, headers=headers, data=json.dumps(payload))
	response.raise_for_status()
except requests.RequestException as e:
	print("Block user action due to CAPTCHA failure: Request failed")
	exit()

result = response.json()

if result.get('success'):
	signals = result['data']['signals']
	print(f"Signals score: {signals['score']}")

	spam_filter = result['data'].get('spamFilter')
	if spam_filter:
		print(f"Spam filter score: {spam_filter['score']}")

	# Decide whether to proceed with the user action or block it depending on the scores
	if signals['score'] < 0.5:
		print(f"Block user action due to low signals score: {signals['score']}")
		exit()
	if spam_filter and spam_filter['score'] < 0.5:
		print(f"Block user action due to low spam filter score: {spam_filter['score']}")
		exit()

	print("Proceed with user action.")
else:
	error = result.get('error', 'Verification failed')
	print(f"Block user action due to CAPTCHA failure: {error}")