What is ByPass Mode

ByPass Mode is designed to ensure that service degradation can be achieved in a timely and controlled manner in any extreme situation, as the overall protection machanism to guarantee customer’s normal business process. GeeTest developed an interface independent from main communication process sending heartbeat signal for monitoring the service availability. When there is no response from GeeTest server, the service can be degraded to run offline mode which guarentee the normal business process won’t be affected.

Why configuring ByPass mode is important

We realized that some users would ignore configuration ByPass mode, which is crucial for handling unforeseen circumstances. We strongly recommend configure ByPass mode and have it fully tested to avoid any interruption. The following is ByPass commmunication flow chart:


Installation Steps

1. Download ByPass demo file

​ The SDK project file containing ByPassDemo is offered here

2. Configure ByPass mode

Check the status via ByPass API (success: GeeTest cloud service is working; fail: GeeTest cloud service is down). There are 2 methods to check the status:

Method 1: Check ByPass status code from database when client SDK sends request to GeeTest server

When the database space is enough, use polling function to send periodic request to GeeTest server via ByPass API and save the status in database.( Redis is used in Demo code). Before client SDK sends reqeust to GeeTest server, the status code will be checked to decide whether to proceed to communicate with GeeTest server based on the status code. If the status is Fail, then you can choose not to load the CAPTCHA challenge.Check the sample code.

Method 2:Make instant request via ByPass API everytime before invoking CAPTCHA

This approach is suitable for the user who doesn’t have enough DB space for storing the extra parameters and has concern about resource consumption from periodically checking the status. If the status is Fail, then you can choose not to load the CAPTCHA challenge. Check the sample code.

3.Start ByPass mode

​ After configuring the ByPass mode, start ByPass mode in primary verification(/register.php) and secondary verification(/validate. php).

  • In primary verification process(/register.php) ,call localRegister() and set the result.
if(bypasscache === "success") {

result = await gtLib.register(digestmod, params);

} else {

result = await gtLib.localRegister();


res.set('Content-Type', 'application/json;charset=UTF-8')

return res.send(result.data);
  • In secondary verification process(/validate.php), call failValidate() and set the result.
if(bypasscache === "success") {

result = await gtLib.successValidate(challenge, validate, seccode, params);

} else {

result = gtLib.failValidate(challenge, validate, seccode);


Frontend will be notified once the result is set. If there is an orange sign on the right upper corner of CAPTCHA widget, it means the CAPTCHA is now offline.

4. Test ByPass mode

Please fully test it after configuring ByPass mode to ensure it can switch back and forth. There are 2 ways you can choose to test:

To test it on your own

When the communication with GeeTest server is cut, ByPass mode will be started automatically. CAPTCHA service is degraded and will not hinder the normal process。Follow the next steps to simulate the case:

  1. Change GEETEST_ID in the config file to invalid value
    For example set GEETEST_ID in geetest_config to 1234567890
  2. Change ByPass API to wrong URL
    For example set BYPASS_URL in geetest_config to http://www.google.com

  3. Change the hosts to invalid IP address

For example change Hosts file: bypass.geetest.com

Contact GeeTest service team

Contact GeeTest service team and provide the CAPTCHA ID on which you want to test. Then the fail status will be sent from GeeTest server and you’ll be able to see that CAPTCHA service goes to offline.

ByPass API reference