1. The user loads the website, which includes nCAPTCHA’s challenge Javascript.

2. The user’s browser requests a challenge to nCAPTCHA servers, which returns the challenge and a token that identifies the challenge.

3. The user completes the form with the CAPTCHA and sends the answer with the challenge ID.

4. Your server sends the CAPTCHA’s answer to nCAPTCHA’s server, which verifies and returns the result.

5. If the answer is correct, it allows the user to access the required service, information, or section (e.g., posting a comment, registering to the site, or voting in a poll). If the answer is incorrect, it requests the user to solve the CAPTCHA again.

API Keys

To use nCAPTCHA, you need to obtain your public and private keys.

The public key is used to show an nCAPTCHA and can be seen by your website users.

The private key is used to validate an nCAPTCHA and should only be known by yourself.

An nCAPTCHA challenge shown with a specific public key can only be validated using its corresponding private key.

How to display nCAPTCHA

There are two ways to display nCAPTCHA:

• Standard Display: Use this display when you need the nCAPTCHA to be shown immediately when loading one of your website’s pages. (e.g., within a registration page or a recover password page.)

• Asynchronous Display: Use this display when you want to load the nCAPTCHA when the user performs an action. (e.g., for an online poll on your website’s main page that uses nCAPTCHA for vote validation, nCAPTCHA will only be displayed when the user tries to submit a vote.) Asynchronous displays avoid requesting nCAPTCHA challenges that the user won’t validate.

nCAPTCHA standard display

To use nCAPTCHA in standard display mode, include in your website a script element with the URL: https://api.ncaptcha.com/challenge.php?k=your_public_key as the source, specifying your public key in the parameter k as shown below:

    <form action="" method="post">

        <script src="https://api.ncaptcha.com/challenge.php?k=your_public_key" type="text/javascript"></script>

    </form>

nCAPTCHA asynchronous display

To use nCAPTCHA's asynchronous functionality, include the script //cdn.ncaptcha.com/js/bcaptcha.js.

Use the function BrandCaptcha.initAsync(publickey, containerId), sending as the first parameter your public key and, as a second parameter, the HTML’s element ID indicating where you want to locate the nCAPTCHA (The content of the HTML element will be replaced by the nCAPTCHA).

Once the nCAPTCHA is generated, it can be reloaded (if needed) using the function BrandCaptcha.reload().

<form action="" method="post">
     <div id="container"></div>
     <input type="submit" value="submit" />

     <script src="//cdn.ncaptcha.com/js/bcaptcha.js" ></script>
     <script>
        BrandCaptcha.initAsync("su_public_key", "container");
     </script>
</form>

Error Codes

invalid-public-key: The public key is invalid or non­existent

invalid-referer: The domain from where the request is being made doesn’t match the domain associated with the key

invalid-request: Invalid request

no-challenge-available: There are no available challenges to show

error: General error

How to validate an nCAPTCHA

After configuring nCAPTCHA to display correctly, the verification form needs to be configured to check if the user’s answer is correct. This is done by making a POST request to https://api.ncaptcha.com/verify.php

API Request

URL: https://api.ncaptcha.com/verify.php

POST

Parameters

privatekey: Your private key

remoteip: The IP address of the user that answered/solved the nCAPTCHA

challenge: The "brand_cap_challenge" value sent through the form, representing the challenge ID

response: The value of “brand_cap_answer” sent through the form, which represents the user’s answer.

API Reply

A series of chains delimited by \n. To read it, separate the lines and read each field.

Line 1: true or false. being "true" the value for a correct answer

Line 2: If Line 1 is false this will be an error code

Error Codes

incorrect-captcha-sol: The user’s answer is incorrect

error: General Error

Personalizing nCAPTCHA

nCAPTCHA allows personalization of the CAPTCHA box through a series of options. The way to select these options will depend on the nCAPTCHA being set up in the standard or asynchronous display.

Standard display options

Declare the variable brandcaptchaOptions prior to nCAPTCHA’s script inclusion. This variable should contain an associative array with the name of the option as a key and the selected value.

    <script>
        var brandcaptchaOptions = {
            option: 'value'
        };
    </script>

Asynchronous display options

Using nCAPTCHA’s asynchronous display, define the options while calling the method initAsync, sending as a third parameter an associative array with the name of the option as the key and the selected value.

    <script>
        BrandCaptcha.initAsync("your_public_key", "container", { lang: 'en' });
    </script>

Options

lang

Language in which you want to display nCAPTCHA’S box texts (e.g., “Your Answer”, “Reload”, etc.).
Accepted values are:

• en for English.

• es for Spanish.

• pt for Portuguese.

theme

Select the theme that you want to apply to the captcha box.
Accepted values are:

• default

onComplete

Function to be called when nCAPTCHA has loaded.
This event also triggers when nCAPTCHA reloads.

protocol

Access protocol for request.
Accepted values are:

• http for Hypertext Transfer Protocol.

• https for Hypertext Transfer Protocol Secure
  
  
  If needed, we offer a variety of plugins for alternative programming environments, such as PHP, ASP.NET, ASP (Classic), JAVA, and WordPress. We recommend you use one of these before developing your implementation. Go to the plugin repository.