Solving reCAPTCHA v2 with Playwright and DeathByCaptcha in Java

Solving reCAPTCHA v2 with Playwright and DeathByCaptcha in Java

Posted on 2026-11-20 | 3 min read | Category: playwright | By DeathByCaptcha Engineering Team

Playwright


Solving reCAPTCHA v2 with Playwright and DeathByCaptcha in Java

Java teams that automate browser flows usually reach for Playwright, but the captcha is still the wall at the end of the form. This guide shows the official Java example: it opens a page with reCAPTCHA v2, reads the sitekey, asks DeathByCaptcha for a token, injects it and submits the form.

The example lives in the official client repository:

  • samples/src/main/java/examples/ExamplePlaywrightRecaptchaV2.java

What you need

  • JDK 21 or newer and Maven.
  • A DeathByCaptcha account with balance.
  • The Playwright browsers installed for Java (the sample downloads them on first run through its Maven dependencies).

Credentials

The sample reads the environment first and falls back to a .env file in the working directory:

DBC_USERNAME=your_username
DBC_PASSWORD=your_password
# or
DBC_AUTHTOKEN=your_authtoken

Nothing is written to the repository, and the token is never printed.

Run it

git clone https://github.com/deathbycaptcha/deathbycaptcha-api-client-java.git
cd deathbycaptcha-api-client-java
mvn -Psamples -DskipTests compile
mvn -Psamples exec:java -Dexec.mainClass="examples.ExamplePlaywrightRecaptchaV2"

Headless is the default. To watch the browser:

mvn -Psamples exec:java \
  -Dexec.mainClass="examples.ExamplePlaywrightRecaptchaV2" \
  -Dplaywright.headless=false

The core of the sample

The flow is five steps: launch, detect, solve, inject, submit.

try (Playwright playwright = Playwright.create()) {
    Browser browser = playwright.chromium().launch(
        new BrowserType.LaunchOptions().setHeadless(isHeadlessEnabled()));

    BrowserContext context = browser.newContext();
    Page page = context.newPage();

    page.navigate("https://www.google.com/recaptcha/api2/demo");
    page.waitForSelector("#recaptcha-demo");

    String sitekey = page.getAttribute("#recaptcha-demo", "data-sitekey");

    JSONObject params = new JSONObject();
    params.put("googlekey", sitekey);
    params.put("pageurl", "https://www.google.com/recaptcha/api2/demo");

    Client client = new HttpClient(username, password);
    Captcha captcha = client.decode(params);

    injectToken(page, captcha.text);
    page.click("#recaptcha-demo-submit");
    page.waitForSelector(".recaptcha-success");
    System.out.println(page.textContent(".recaptcha-success"));
}

The injection helper passes the token as an argument instead of building JavaScript source with string concatenation, sets the response field, fires the input and change events and calls the widget callback when it exists:

page.evaluate(
    "(token) => { /* set g-recaptcha-response, dispatch events, call callback */ }",
    token);

That last part matters. Many sites do not accept the token just because the hidden field is filled; the widget callback is what unlocks the submit button. The sample calls it, and fails loudly when the field is missing instead of submitting an empty token.

Why the token is requested from DeathByCaptcha

reCAPTCHA v2 protects a form with a token that must be tied to the page URL and the sitekey. The browser does not have to solve the challenge: the service returns a valid token for that pair, and the page accepts it when it is injected before submission.

The request uses type 4 and sends googlekey plus pageurl in token_params. The same shape works for reCAPTCHA v3 (type=5, with action and min_score) and for Enterprise (type=25, in token_enterprise_params).

Things to know

  • The sample stops at the demo page. It uses Google's own reCAPTCHA demo, which exists for testing. Do not point automation at a site you do not own or have permission to test.
  • Token types tied to the exit IP. Turnstile, Amazon WAF and DataDome tokens are only valid from the same IP that solved them. When you use those types, pass a proxy to both the browser and the service.
  • No silent success. If the response field is not found, the sample raises and prints the state; a submitted form with an empty token is worse than a clear failure.
  • The online test runs in CI. The repository runs the same flow as an integration test on every push, with the account secrets kept in GitHub.

Next steps

The same pattern works for the other token types: change the type and the *_params key, keep the injection step per widget. The repository also has a PuppeteerSharp sample and the per-type examples for image, GeeTest, Turnstile and WAF.

  • Java client: https://github.com/deathbycaptcha/deathbycaptcha-api-client-java
  • API documentation: https://deathbycaptcha.com/api

Common pitfalls

  • Using a CAPTCHA solving service for illegitimate purposes instead of legitimate automation and testing.
  • Hard-coding credentials or API keys in client-side code that users can inspect.
  • Sending the wrong CAPTCHA type parameter, which returns incorrect or empty responses.
  • Failing to poll for the solution status and not handling timeouts gracefully.
  • Scaling automation without monitoring error rates, response times, and CAPTCHA type coverage.
DBC
Written by DeathByCaptcha Engineering Team
DeathByCaptcha engineers build and operate the CAPTCHA solving technology behind this site. Articles are written by our technical team and checked for accuracy before publishing.
Reviewed by DeathByCaptcha Editorial Team

Get your API key — start solving

Free to try · No credit card · Python, Node.js, Java, C# SDKs

Get your API key


Status: OK

Servers are fully operational with faster than average response time.
  • Average solving time
  • 3 seconds - Normal CAPTCHAs (1 min. ago)
  • 4 seconds - reCAPTCHA V2, V3 (1 min. ago)
  • 4 seconds - others (1 min. ago)
Chrome and Firefox logos
Browser extensions available

Updates

  1. Nov 19: We are currently updating our cryptocurrency payment processor, Hekelet, so crypto payments may be temporarily unavailable. In the meantime, you can purchase credits through 2Checkout or contact our support team for assistance. We expect normal crypto payment processing to be restored within this week. Thank you for your patience and understanding!
  2. May 13: Crypto payments got better! You can now purchase your CAPTCHAs using cryptocurrency through the Hekelet payment processor at https://deathbycaptcha.com/user-pay and receive an extra 20% FREE CAPTCHA credit with every package purchased this way.
  3. Apr 15: GitHub Updates: We’ve upgraded our libraries, expanded sample code, enhanced documentation, and added support for C++ and Go, making integration smoother than ever. Explore what’s new at github.com/deathbycaptcha!

  4. Previous updates…

Support

Our system is designed to be completely user-friendly and easy-to-use. Should you have any trouble with it, simply email us at DBC technical support emailcom, and a support agent will get back to you as soon as possible.

Live Support

Available Monday to Friday (10am to 4pm EST) Live support image. Link to live support page