logo
bars

GeeTest CAPTCHA v4
and CapMonster Cloud

Captcha solving, website integration, and testing.
Inherited a site with a captcha or another protection layer but no access to the source code? In that case you naturally ask: which solution is installed, is it configured correctly, and how can the workflow be tested?

In this article, we have tried to answer all the key questions. The first step in solving the task is to determine which protection system is being used. To do this, you can refer to the list of popular captchas and anti-bot protection systems, where you will find visual examples and key indicators that help you quickly understand what you are dealing with.

If you discover that your site uses GeeTest CAPTCHA v4, the next step is to study its properties and operation in more detail. In this article, you can also review the instructions on how to integrate GeeTest CAPTCHA v4 so that you fully understand how it functions on your site. This will help you not only understand the current protection, but also properly plan its maintenance.

What is GeeTest CAPTCHA v4
What is GeeTest CAPTCHA v4
GeeTest CAPTCHA v4 (Adaptive CAPTCHA/Behavior Verification) is a more modern version compared to v3, designed to protect websites from automated actions that can damage your resource. The system tracks the behaviour and device characteristics of the site visitor and selects an appropriate challenge: for a real person the check will be as simple as possible — a single click on the captcha widget is enough, and if automation is suspected, the user is given a more complex challenge that must be passed.
Background
Examples of GeeTest CAPTCHA v4
No CAPTCHA
No CAPTCHA
User verification is performed mainly based on behaviour and interaction with the site, without solving explicit challenges.
Icon CAPTCHA
Icon CAPTCHA
Selecting images in the specified order.
IconCrush CAPTCHA
IconCrush CAPTCHA
Swapping elements so that three identical icons line up in a row (like in “match-3” puzzle games).
Slide CAPTCHA
Slide CAPTCHA
A slider to assemble a puzzle or align image elements.
Gobang CAPTCHA
Gobang CAPTCHA
A slider to assemble a puzzle or align image elements.

How to solve GeeTest CAPTCHA v4 with CapMonster Cloud

When testing forms that include GeeTest CAPTCHA v4, you often need to verify that the captcha works and is integrated correctly.

You can verify the captcha embedded on your site manually.

  • Open the form page and make sure the captcha renders.
  • Try submitting the form without solving it — the server should return an error.
  • After a successful solution, the form must be submitted without issues.

For automatic solving you can use tools like CapMonster Cloud, which accepts captcha parameters, processes them on its servers, and returns a ready-to-use token. Insert this token into the form to pass the check without user interaction.

Working with CapMonster Cloud via API typically involves the following steps:

Creating a taskCreating a task
arrow
Sending an API requestSending an API request
arrow
Receiving the resultReceiving the result
arrow
Placing the token on the pagePlacing the token on the page
arrow
Solving GeeTest CAPTCHA v4 using ready-made libraries
CapMonster Cloud provides ready-to-use libraries for convenient work in Python, JavaScript (Node.js) and C#.
Python
JavaScript
C#
Solving, injecting the token, and submitting the form
A Node.js example for the full captcha-solving cycle on your web page. Possible approaches: use HTTP requests to fetch the HTML and captcha parameters, send the answer and process the result; or, with automation tools (for example, Playwright), open the page, wait for the captcha, send the parameters (for testing you can send both correct and incorrect data), get the solution via the CapMonster Cloud client, inject the token into the form and see the result.
// npm install playwright @zennolab_com/capmonstercloud-client

import { chromium } from "playwright";
import {
  CapMonsterCloudClientFactory,
  ClientOptions,
  GeeTestRequest
} from "@zennolab_com/capmonstercloud-client";

const CAPMONSTER_API_KEY = "YOUR_CAPMONSTER_API_KEY";

async function solveGeetestV4(pageUrl) {
  const browser = await chromium.launch({ headless: false });
  const context = await browser.newContext({ viewport: null });
  const page = await context.newPage();

  let detected = null;
  let solutionObj = null;

  // 1. Intercept the /load response (detect captcha_id, challenge, etc.)
  page.on("response", async (response) => {
    const url = response.url();
    if (!url.startsWith("https://gcaptcha4.geetest.com/load?")) return;

    const params = new URLSearchParams(url.split("?")[1] || "");
    const captchaId = params.get("captcha_id");
    const challenge = params.get("challenge");
    const captchaType = params.get("captcha_type");

    if (captchaId && challenge) {
      detected = { captchaId, challenge, captchaType };
      console.log("Detected GeeTest v4 load:", detected);
    }
  });

  // 2. Load the page
  console.log("Opening page:", pageUrl);
  await page.goto(pageUrl, { waitUntil: "domcontentloaded" });

  // 3. Wait until /load is captured
  console.log("Waiting for GeeTest /load...");
  while (!detected) {
    await page.waitForTimeout(500);
  }

  // 4. Send the task to CapMonster Cloud
  console.log("Sending task to CapMonster...");
  const cmc = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: CAPMONSTER_API_KEY })
  );

  const task = new GeeTestRequest({
    websiteURL: pageUrl,
    gt: detected.captchaId,
    challenge: detected.challenge,
    version: "4",
    initParameters: {
      riskType: detected.captchaType || "slide"
    }
  });

  const solveRes = await cmc.Solve(task);
  const sol = solveRes.solution || solveRes;

  solutionObj = {
    captcha_id: sol.captcha_id || detected.captchaId,
    captcha_output: sol.captcha_output,
    lot_number: sol.lot_number,
    pass_token: sol.pass_token
  };

  console.log("Got solution from CapMonster:", solutionObj);

  // 5. Substitute your values into /verify to get a successful response
  await page.route("https://gcaptcha4.geetest.com/verify*", async (route) => {
    console.log("Intercepted /verify, injecting fake success...");
    const body = `geetest_${Date.now()}(${JSON.stringify({
      status: "success",
      data: {
        result: "success",
        seccode: {
          captcha_id: solutionObj.captcha_id,
          captcha_output: solutionObj.captcha_output,
          lot_number: solutionObj.lot_number,
          pass_token: solutionObj.pass_token
        }
      }
    })})`;

    await route.fulfill({
      status: 200,
      contentType: "application/javascript",
      body
    });
  });

  // 6. Imitate a user action (for example, click the captcha button)
  console.log("Waiting for captcha interaction...");
  await page.waitForTimeout(3000);

  // Example of a verification call:
  try {
    await page.click('.geetest_btn'); // captcha button
    console.log("Clicked captcha button");
  } catch {
    console.log("Captcha button not found");
  }

  // Sometimes you need to call verify() manually:
  await page.evaluate(() => {
    if (window.initGeetest4 && typeof verify === "function") {
      verify();
    }
  });

  console.log("Waiting for verification request...");
  await page.waitForTimeout(3000);

  await browser.close();

  return { detected, solution: solutionObj };
}
(async () => {
  const url = "https://example.com"; // replace with a page that has GeeTest v4
  const res = await solveGeetestV4(url);
  console.log("FINISHED:", res);
})();
How to connect GeeTest CAPTCHA v4 to your site
To clearly understand how the captcha works on your site, how the validation behaves, and how to reconnect or reconfigure it, we recommend reading this section. It describes the protection setup process so you can quickly cover all the details.

1. Sign up or log in to your GeeTest account.

2. Go to the Captcha Dashboard and select Behavior Verification v4:

HowTo Connect image 1

3. In the dashboard click + Create application.

4. Specify APP/website name (the name of the site or application where the captcha will be used), Address (the main domain of the site where the captcha will be installed, for example https://example.com), Industry (the site category, for example “E-commerce”, “Social Media”, etc.), then click Confirm.

5. Click Add events next to the newly created application. Set Event – the name of the specific scenario (event) where the captcha will be used, for example login, register, etc.; Device – the platform (for example Web/Wap); Business types – the type of captcha usage scenario (for example, Sign-up / Sign-in — registration / login). Click Add.

6. Now you will see the ID (used on the client and on the server) and Key (used on the server for verification) of the created captcha in your dashboard:

HowTo Connect image 2

7. Connect the client side

Include the script:

<script src="https://static.geetest.com/v4/gt4.js"></script>

Initialize the CAPTCHA:

initGeetest4(
  { captchaId: "Your CaptchaId" },
  function (captcha) {
    captcha.appendTo("#captcha"); // insert into a page element
  }
);

Important:

  • You must initialize the CAPTCHA when the page loads; otherwise it cannot track user behaviour.
  • If you use multiple CAPTCHAs on one page, call initGeetest4 separately for each.
  • If you use the CAPTCHA inside an iframe, add sandbox="allow-scripts allow-popups".

Code exampleCode example
arrow

8. Configure the server side.

When a user passes the CAPTCHA on the frontend, a set of parameters is generated. You must send these parameters to the backend and then verify them via GeeTest’s secondary API to confirm that the check was successful.

Secondary verification API:

url
http://gcaptcha4.geetest.com/validate

  • Method: GET/POST
  • Content-Type: application/x-www-form-urlencoded
  • Response: JSON

Main request parameters

  • lot_number – verification serial number
  • captcha_output – verification payload
  • pass_token – verification token
  • gen_time – verification generation time
  • captcha_id – CAPTCHA ID
  • sign_token – signature for verification

Example of a successful responseExample of a successful response
arrow

Example of CAPTCHA verification in PHPExample of CAPTCHA verification in PHP
arrow

Background
Possible errors and debugging
Bug Icon
Invalid parameters
The captcha is not displayed or returns errors like invalid-captcha-id / invalid-challenge. Make sure that you use up-to-date captcha_id and challenge values that match your page. These parameters are dynamically generated on every /load request.
Bug Icon
Solution timeout
The captcha solution was not received in time. Increase the wait time when using automatic solving services (for example, CapMonster Cloud) and make sure the connection to the API is stable.
Bug Icon
Empty fields
captcha_output, pass_token or lot_number are not passed to the page or to the verification request. Make sure these values are correctly inserted into hidden form fields or into the request body to your server.
Bug Icon
Response success=false
The token is expired, reused, or forged. Enable logging of all requests and responses from the verification server to track fields like error_code or error_msg.
Protection resilience checks
After integration, make sure the system really protects the site from automated actions.
Security and optimization tips
Store the <b>captcha key (secret KEY) on the server only</b>; never expose it to the client side.
Log error codes during verification (<b>error-codes</b> or fields from the server response) so you understand why checks fail.
Add links to your <b>Privacy Policy</b> and <b>GeeTest Terms of Use</b> at the bottom of the form if required by license or internal policies.
Conclusion

If you’ve taken over a website that already has a captcha or another protection system installed, but you don’t have access to the code, don’t worry! It’s quite easy to identify which technology is being used. To verify that everything works correctly, you can use the CapMonster Cloud recognition service in an isolated test environment to make sure that the token processing mechanism and the validation logic are functioning properly.

In the case of GeeTest CAPTCHA v4, it’s enough to detect the system, observe its behavior, and confirm that the protection is working correctly. In this article, we showed how to identify GeeTest CAPTCHA v4 and where to find instructions on how to integrate or reconfigure it, so you can confidently maintain the protection and keep its operation under control.

Conclusion