All the examples in this document are based on java servlet.

Development environment

Item Description
compatibility JAVA SE 1.6 or higher
Dependency java-json.jar、servlet-api.jar
Web server tomcat 7 or higher


Item Description
Data communication flow chart Data Communication flow chart
Download SDK gt3-server-maven-sdk


Download​ ​SDK

There are two ways to download SDK.

Use​ ​command​ ​line​ ​to​ ​get​ ​from​ ​Github

git clone https://github.com/GeeTeam/gt3-server-maven-sdk.git

Download​ ​SDK​ ​manually

Get​ ​the​ ​latest​ ​SDK​ ​from Github: gt3-server-maven-sdk (in .zip format).

Import SDK

Copy​ ​and​ ​paste​ ​/src/main/java/com/geetest/sdk/GeetestLib.java​ ​into​ ​your​ ​project.

Import​ the ​SDK

import com.geetest.sdk.GeetestLib

Configure key pair and modify the request

Configure key pair

Get your key pair from GeeTest Dashboard. The key pair consists of a public​ ​key(captcha ID) and a private​ ​key (KEY)​. Then, configure the key pair in the following path.


Modify the request (optional)

Variable Description
user_id User identification. If you concern about the risk of user information, you can preprocess (e.g. hashed) it.
client_type Type of client. Web (web browser for computers),h5 (mobile browser,including webview),native(native mobile app),unknown (unknow client type)
ip_address IP address for client requesting your server , unknow means unknow IP address

API example

Captcha initialization

Initiate captcha via API1, get challenge and set the status.

public class FirstRegisterServlet extends HttpServlet {

protected void doGet(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
GeetestLib gtLib = new GeetestLib(GeetestConfig.geetestId,

String userId = "test";
HashMap<String, String> paramMap = new HashMap<String, String>();
paramMap.put("user_id", userId); //网站用户id
paramMap.put("client_type", "web"); //web:电脑上的浏览器;h5:手机上的浏览器,包括移动应用内完全内置的web_view;native:通过原生SDK植入APP应用的方式
paramMap.put("ip_address", ""); //传输用户请求验证时所携带的IP

// 进行一次验证,得到结果
GeetestLibResult result = gtLib.register(paramMap);
// 将userid设置到session中
// 注意,此处api1接口存入session,api2会取出使用,格外注意session的存取和分布式环境下的应用场景
request.getSession().setAttribute("userId", userId);

PrintWriter out = response.getWriter();

// 注意,不要更改返回的结构和值类型


Notice:status indicates the status of API1. 1 represents normal status, or 0 represents downtime.

gtServerStatus is stored in session from API1. API2 will read the value from session and check the status. 1 will start the 2nd verification process.0 will start the fail-back mode.

successis the value that API1 returns to the front-end. 1 shows normal page and 0 shows downtimw page.

Secondary verification (API2), including uptime and downtime

public class SecondValidateServlet extends HttpServlet {

protected void doPost(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
GeetestLib gtLib = new GeetestLib(GeetestConfig.geetestId,

String challenge = request
String validate = request.getParameter(GeetestConfig.GEETEST_VALIDATE);
String seccode = request.getParameter(GeetestConfig.GEETEST_SECCODE);

PrintWriter out = response.getWriter();

int gt_server_status_code = 0;
String userId = "";
try {
// 从session中获取一次验证状态码和userId
gt_server_status_code = (Integer) request.getSession()
userId = (String) request.getSession().getAttribute("userId");
} catch (Exception e) {
+ e.toString());

HashMap<String, String> param = new HashMap<String, String>();
param.put("user_id", userId); //网站用户id
param.put("client_type", "web"); //web:电脑上的浏览器;h5:手机上的浏览器,包括移动应用内完全内置的web_view;native:通过原生SDK植入APP应用的方式
param.put("ip_address", ""); //传输用户请求验证时所携带的IP

GeetestLibResult result = null;
// gt_server_status_code 为1代表一次验证register正常,走正常二次验证模式;为0代表一次验证异常,走failback模式
if (gt_server_status_code == 1) {
result = gtLib.successValidate(challenge, validate, seccode, param);
} else {
// gt-server非正常情况,进行failback模式本地验证
result = gtLib.failValidate(challenge, validate, seccode);

// // 注意,不要更改返回的结构和值类型

Notice: When status = 0, it means GeeTest server experiencing downtime and it will go to failback mode. No more requests will be made to GeeTest server.

How to simulate the Failback mode? Please fill in an incorrect string (e.g. 123456789) for the captcha ID. Then, it will enter the Failback mode.

Run demo

Export​ ​demo​ ​in​ ​.war​ ​format​ ​and​ ​put​ ​it​ ​under ​tomcat7/webapps. ​Then start ​tomcat.

To view the demo, please visit​ ​​http://localhost:8080/gt3-server-maven-sdk ​in​ ​browser​.

Troubleshooting: secondary verification failure

  1. SDK internal logic errors. Please check: a) whether session is stored and read successfully, b) whether the code could successfully proceed to the module which send a request to GeeTest server, c) check the return value of GeeTest server.
  2. Multiple submission. The API which initiates the secondary verification is only available for one time.
  3. The challenge is inconsistent. Please ensure the consistency of challenge during the whole verification process.
  4. Check if gt and key in the code are correct in SDK. Please check if the parameters have been passed correctly.
  5. Please provide challenge to our service team. They could help you to check the log.