Docs
Integrations
Java

Java

To use this integration you need to create an API key in your account.
If you have a working reCAPTCHA integration, check our migration guide for easy instructions.

This is a server-side SDK, which you would use to verify captcha solution against Private Captcha API. This SDK does not solve puzzles on the client side (used to protect APIs).

GitHub repository
Maven package

Installation

Minimum supported Java version is 11

Maven

Add the following dependency to your pom.xml:

<dependency>
    <groupId>com.privatecaptcha</groupId>
    <artifactId>private-captcha-java</artifactId>
    <version>0.0.1</version>
</dependency>

Gradle

Add the following to your build.gradle:

implementation 'com.privatecaptcha:private-captcha-java:0.0.1'

Usage

Always check our security recommendations when using this integration.

Note

Before using this SDK, you’ll need an API key. If you don’t have one yet, see how to create it in the Getting Started guide.

Basic Verification 

import com.privatecaptcha.*;

PrivateCaptchaClient client = new PrivateCaptchaClient(
    new PrivateCaptchaConfiguration("pc_your_api_key")
);

try {
    VerifyOutput output = client.verify(new VerifyInput(solution));
    
    if (output.ok()) {
        System.out.println("Verification successful!");
    } else {
        System.out.println("Verification failed: " + output.getErrorMessage());
    }
} catch (PrivateCaptchaHttpException e) {
    System.err.println("HTTP error: " + e.getStatusCode());
} catch (VerificationFailedException e) {
    System.err.println("Verification failed after " + e.getAttempts() + " attempts");
}

Configuration

Client options 

import java.time.Duration;

PrivateCaptchaConfiguration config = new PrivateCaptchaConfiguration("pc_your_api_key")
    .setDomain(Domains.GLOBAL)
    .setFormField("private-captcha-solution")
    .setFailedStatusCode(403)
    .setConnectTimeout(Duration.ofSeconds(10))
    .setReadTimeout(Duration.ofSeconds(30));

PrivateCaptchaClient client = new PrivateCaptchaClient(config);

Verification Input Options 

VerifyInput input = new VerifyInput(solution)
    .setSitekey("your-sitekey")
    .setMaxBackoffSeconds(20)
    .setMaxAttempts(5);

VerifyOutput output = client.verify(input);

Server Integration

The verifyRequest() method provides easy integration with any HTTP server framework using the FormParameterExtractor functional interface:

Servlet (Jakarta/Javax) 

@WebServlet("/submit-form")
public class FormServlet extends HttpServlet {
    
    private final PrivateCaptchaClient captchaClient = new PrivateCaptchaClient(
        new PrivateCaptchaConfiguration(System.getenv("PC_API_KEY"))
    );
    
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
            throws ServletException, IOException {
        try {
            VerifyOutput output = captchaClient.verifyRequest(request::getParameter);
            
            if (!output.ok()) {
                response.sendError(captchaClient.getFailedStatusCode(), 
                    "Captcha verification failed: " + output.getErrorMessage());
                return;
            }
            
            // Process the form...
            response.getWriter().println("Form submitted successfully!");
            
        } catch (Exception e) {
            response.sendError(captchaClient.getFailedStatusCode(), 
                "Captcha verification error");
        }
    }
}

Spring MVC 

@RestController
public class FormController {
    
    private final PrivateCaptchaClient captchaClient = new PrivateCaptchaClient(
        new PrivateCaptchaConfiguration(System.getenv("PC_API_KEY"))
    );
    
    @PostMapping("/submit-form")
    public ResponseEntity<String> submitForm(HttpServletRequest request) {
        try {
            VerifyOutput output = captchaClient.verifyRequest(request::getParameter);
            
            if (!output.ok()) {
                return ResponseEntity.status(captchaClient.getFailedStatusCode())
                    .body("Captcha verification failed: " + output.getErrorMessage());
            }
            
            return ResponseEntity.ok("Form submitted successfully!");
        } catch (Exception e) {
            return ResponseEntity.status(captchaClient.getFailedStatusCode())
                .body("Captcha verification error");
        }
    }
}

Spring WebFlux 

@RestController
public class FormController {
    
    private final PrivateCaptchaClient captchaClient = new PrivateCaptchaClient(
        new PrivateCaptchaConfiguration(System.getenv("PC_API_KEY"))
    );
    
    @PostMapping("/submit-form")
    public Mono<ResponseEntity<String>> submitForm(ServerWebExchange exchange) {
        return exchange.getFormData().map(formData -> {
            try {
                VerifyOutput output = captchaClient.verifyRequest(formData::getFirst);
                
                if (!output.ok()) {
                    return ResponseEntity.status(captchaClient.getFailedStatusCode())
                        .body("Captcha verification failed");
                }
                
                return ResponseEntity.ok("Form submitted successfully!");
            } catch (Exception e) {
                return ResponseEntity.status(captchaClient.getFailedStatusCode())
                    .body("Captcha verification error");
            }
        });
    }
}

Vert.x 

router.post("/submit-form").handler(ctx -> {
    try {
        VerifyOutput output = captchaClient.verifyRequest(ctx.request()::getParam);
        
        if (!output.ok()) {
            ctx.response()
                .setStatusCode(captchaClient.getFailedStatusCode())
                .end("Captcha verification failed");
            return;
        }
        
        ctx.response().end("Form submitted successfully!");
    } catch (Exception e) {
        ctx.response()
            .setStatusCode(captchaClient.getFailedStatusCode())
            .end("Captcha verification error");
    }
});

Javalin 

app.post("/submit-form", ctx -> {
    try {
        VerifyOutput output = captchaClient.verifyRequest(ctx::formParam);
        
        if (!output.ok()) {
            ctx.status(captchaClient.getFailedStatusCode())
               .result("Captcha verification failed");
            return;
        }
        
        ctx.result("Form submitted successfully!");
    } catch (Exception e) {
        ctx.status(captchaClient.getFailedStatusCode())
           .result("Captcha verification error");
    }
});
Last updated on
Ruby