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

English
Spanish
Russian
Chinese
French
Hindi
Arabic
Bengali
Indonesian
Portuguese
com, 