Skip to content
Captcha.party

Getting started

The onboarding consists of three parts:

  1. Getting your credentials
  2. Setting up client-side integration
  3. Setting up server-side validation

1. Getting your credentials

There are two credentials you will need to grab:

  • your sitekey (this will be public)
  • your secret key (this is private, never share it!)

Head to the Dashboard and go to Add site.

Follow the onboarding process on the site. Once you are through with it, you should be presented your sitekey and secret key. Make sure to write down your secret key, you won’t have a second chance to access it.

2. Setting up client-side integration

Now it’s time to install the Captcha.party widget on your site. To do this you need to include our script.

2.1 Install script

Simply add this script element to your <head> element:

<script src="https://global.captcha.party/public/api.js" async defer></script>

2.2 Install widget

Now that you’ve added the script, you need to tell it to render the widget.

2.2.1 HTML rendering

HTML rendering (also called implicit rendering) is where you use HTML to render the widget. You can set the options directly on a HTML element, like so:

<div class="p-captcha" data-sitekey="..."></div>

A hidden input field with the CAPTCHA solution will be created automatically and included in form submits.

Explanation:

  1. class="p-captcha" tells the script to render a widget here
  2. data-sitekey="..." tells the script what your sitekey is

There are more data- options than just sitekey, you can find them here.

2.2.2 Javascript rendering

You can also use the pcaptcha Javascript API that is automatically installed through our script.

To render a challenge use the pcaptcha.render() API:

function initCaptcha() {
  const container = document.querySelector("#captcha");
  window.pcaptcha.render({
    container,
    sitekey: "...",
    onSuccess: (solution) => {
      alert("solved! " + solution);
    },
  });
}


if (window.pcaptcha) {
  // script loaded already
  initCaptcha();
} else {
  // script isn't loaded yet, so lets wait until it is
  // note: this assumes you added the script with `id="captcha-api"`
  const script = document.querySelector("#captcha-api");
  script.addEventListener("load", initCaptcha);
}

You can find more examples in the Widget API documentation.

3. Setting up server-side integration

In the form data sent to the server, there will be an additional field called p-captcha-solution. You can send this field to our siteverify API to verify the CAPTCHA was solved correctly.

3.1 Sending the request

Send a POST request to https://global.captcha.party/api/v0/siteverify with the following arguments:

KeyDescription
solutionthe solution from the extra field
secretyour secret key from the first step
remoteip(optional) ip of the user (can be reduced, see aside)

3.2 Response

The response will always have the status code 200 and have a JSON body like the following (very reduced example):

{
    "success": true|false,
    "error": [...],
}

If success is false, you should reject the request.

You can continue to learn more about response payloads or read about best practices here.