The reputation of your digital commerce businesses might be severely tarnished by one outage . Unfortunately, outages and downtimes cannot be completely avoided. As known, many of our clients deploy GeeTest CAPTCHA at the crucial gateways. Our tech team upgraded our Failback mode to ByPass mode, which is more robust to the unexpected incidents, out of the concern that the clients' online business might be affected by CAPTCHA down. The previous Failback mode is the mechanism of making CAPTCHA service offline when GeeTest CAPTCHA is down, to avoid any interruption to the normal business process. There is downside of Failback mode. Despite the situation is extreme and rare, the Failback mode won’t be started if the service is still intermittently available. The ByPass API enables you knowing the latest status before communicating with GeeTest server, minimizing the risk of jeopardizing the business process. Even though we guarantee 99.9% SLA, the Force Majeur is not in our control. Therefore, ByPass mode and such disaster recovery mechanism were developed to ensure complete satisfaction.

If you are still using old version SDK, the Failback mode is still effective. You can proceed to the Failback part for instructions. We also provide the option for you to switch to newer version SDK and the latest SDK files can found in the developer’s documentation. Choose the programming language before downloading the SDK. The new version SDK contains new gt.lib file and demo code, offering the detailed instructions for you to configure ByPass mode. Technically, you can simply replace gt.lib file with the new one in your existing SDK.

ByPass mode

In general, our SDKs provide demo code assisting you do the implementation. As we observe from our clients who are using our service, most of them would ignore the part of configuring ByPass mode, which is crucial for handling unforeseen circumstance. A detailed guide with sample code will be introduced here so that you will have a better understanding of how ByPass mode can be implemented and how it works.

There are 2 approaches to configure ByPass mode. Please note that all the instructions are given in the example of NodeJS and we offer SDKs in C#, Java, NodeJS, Php, Python and Golang.

Setting the bypass_status

  • Use standalone functions to check and update server status periodically. The sample code in SDK provides one of many methods to write the checking logic.

Use polling function to periodically make API request to check the status.

Write the bypass_status into database and keep updating.

Once the CAPTCHA service is initiated, bypass status has to be checked every time when primary request(/register.php) and secondary request(/validate.php) are made. If the status is “fail”, then both of your client side and server side won’t communicate with GeeTest server and the CAPTCHA service will go offline mode.

  • Make the instant API request to check bypass_status before the primary request(/register.php) and secondary request(/validate.php). 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.

The following code is re-written on the basis of sample code.

What to do after setting the bypass_status?

In the primary verification(/register.php) process, call localRegister() method in gt lib and set the result.

In the secondary verification(/validate.php) process, call failValidate() method and set the result.

During both processes, frontend will be notified and the field offline in initGeetest() method is set to false. Then the bar will be presented with an orange sign on the right upper corner to indicate the offline mode. Then you will know that CAPTCHA service is currently in offline mode.

Failback mode

The Failback mode is still effective if you are using the old version SDK. Simply set failback status in session as true or false, then it can enter the offline mode and the communication with GeeTest’s server will be cut.

How to test?

To test it on your own

Method 1: Change GEETEST_ID in the config file to some invalid value like 1234567890.

Method 2: Change BYPASS_URL in the config file to some invalid address like

Method 3: Modify hosts file to direct to invalid IP

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.

Final thoughts:

It should be noted that the offline mode has very LIMITED protection capability and it’s designed for guaranteeing normal business process under the extreme circumstances. The good practice is that switching to other authentication methods to fully ensure the safety and security once the issue happens.

Start your free trial
Over 320,000 websites and mobile apps worldwide are protected by GeeTest captcha

J. Tian

Product Marketing Manager@GeeTest