Skip to content

Server-side verification

By adding the client side code, you were able to render a Procaptcha widget that identified if users were real people or automated bots. When the captcha succeeded, the Procaptcha script inserted unique data into your form data, which is then sent to your server for verification. The are currently two options for verifying the user’s response server side:

API Verification

Section titled API Verification

To verify that the token is indeed real and valid, you must now verify it at the API endpoint:

https://api.prosopo.io/siteverify

The endpoint expects a POST request with the procaptcha-response token. You must also pass your secret key, which you can obtain by logging in to our customer portal.

A simple test will look like this, where the contents in data is the procaptcha-response token, after being parsed:

// pseudocode
// get the contents of the procaptcha-response token
data = req.body['procaptcha-response']


// send a POST application/json request to the API endpoint
response = POST('https://api.prosopo.io/siteverify', {
    token: data.token,
    secret: 'your_secret_key',
})

Or, as a CURL command:

Terminal window
curl --location 'https://api.prosopo.io/siteverify' \
--header 'Content-Type: application/json' \
--data '{"secret":"your secret key copied from within the customer portal","token":"PROCAPTCHA-RESPONSE"}''

Note that the endpoint expects the application/json Content-Type. You can see exactly what is sent using

Terminal window
curl -vv

in the example above. The response will be a JSON object with a verified key, which will be true if the token is valid and false if it is not.

{
    "verified": true,
}

If you are a Premium Tier customer then you will also receive a risk score associated with the request. The closer the score is to 1, the more likely it is that the request is from a bot.

{
    "verified": true,
    "score": 0.1
}

Verification Code Examples

Section titled Verification Code Examples

JavaScript

Section titled JavaScript
const fetch = require('node-fetch');


async function verifyToken(token) {
    const response = await fetch('https://api.prosopo.io/siteverify', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({secret: 'your_secret_key', token}),
    });
    return response.json().verified || false; // Return verified field, default to false
}

PHP

Section titled PHP
<?php
function verifyToken($token) {
    $url = 'https://api.prosopo.io/siteverify';
    $data = json_encode(["secret" => "your_secret_key", "token" => $token]);
    $options = [
        'http' => [
            'header'  => "Content-Type: application/json\r\n",
            'method'  => 'POST',
            'content' => $data,
        ],
    ];
    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    $response = json_decode($result, true);


    return $response["verified"] ?? false; // Return verified field, default to false
}
?>

Python

Section titled Python
import requests


def verify_token(token):
    url = "https://api.prosopo.io/siteverify"
    data = {"secret": "your_secret_key", "token": token}
    response = requests.post(url, json=data)
    return response.json().get("verified", False)  # Return verified field, default to False

Java

Section titled Java
import java.io.*;
import java.net.*;
import org.json.JSONObject;


public class ProcaptchaVerification {
    public static boolean verifyToken(String token) throws Exception {
        URL url = new URL("https://api.prosopo.io/siteverify");
        HttpURLConnection con = (HttpURLConnection) url.openConnection();
        con.setRequestMethod("POST");
        con.setRequestProperty("Content-Type", "application/json");
        con.setDoOutput(true);


        String jsonInputString = "{\"secret\":\"your_secret_key\", \"token\":\"" + token + "\"}";
        try (OutputStream os = con.getOutputStream()) {
            byte[] input = jsonInputString.getBytes("utf-8");
            os.write(input, 0, input.length);
        }


        BufferedReader br = new BufferedReader(new InputStreamReader(con.getInputStream(), "utf-8"));
        StringBuilder response = new StringBuilder();
        String responseLine;
        while ((responseLine = br.readLine()) != null) {
            response.append(responseLine.trim());
        }


        // Parse JSON response
        JSONObject jsonResponse = new JSONObject(response.toString());
        return jsonResponse.optBoolean("verified", false); // Default to false if not found
    }
}

Verification Package

Section titled Verification Package

We have a JavaScript implementation of the Procaptcha verification package available on npm.

JavaScript / TypeScript Verification

Section titled JavaScript / TypeScript Verification

The @prosopo/server package is available on NPM and can be installed using:

Terminal window
npm install @prosopo/server

To verify a user’s response using JavaScript / TypeScript, simpy import the verify function from @prosopo/server and pass it the procaptcha-response POST data. Types can be imported from @prosopo/types.

import {ProsopoServer} from '@prosopo/server'
import {ApiParams} from '@prosopo/types'


...
// parse the body received from the frontend
const payload = JSON.parse(event.body)


// parse the procaptcha response token
const procaptchaResponse = payload[ApiParams.procaptchaResponse]


// initialise the `ProsopoServer` class
const prosopoServer = new ProsopoServer(config)


// check if the captcha response is verified
if (await prosopoServer.isVerified(procaptchaResponse)) {
    // perform CAPTCHA protected action
}

There is an example TypeScript server NodeJS Server Side Example that you run locally.