All the examples in this document are based on Node framework.

Development environment

Item Description
Compatibility Node 4+
Dependency request, express, body-parser, supervisor, express-session


Item Description
Data communication flow chart Data communication flow chart
Download SDK gt3-node-sdk
Install NPM npm install gt3-sdk


To install the SDK, please download it from Github and import to gt-sdk.js file, or install the SDK (npm install gt3-sdk) via npm package manager. The second method is recommended.

Download​ ​SDK

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

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

Download​ ​SDK​ ​manually

Get​ ​the​ ​latest​ ​SDK​ ​from gt3-node-sdk (in .zip format).

Import SDK

npm install gt3-sdk --save

Install the SDK with npm install gt3-sdk --save in the Node project. Then, import it with the following command.

var Geetest = require('gt3-sdk');

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,include webview),native(native mobile app),unknown (unknow client type)
ip_address Client request for your server IP address, unknow means unknow IP address

API example

The following examples are based on the Click captcha.

Captcha initialization

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

var click = require('./static/click');
app.get("/gt/register-click", function (req, res) {

// 向极验申请每次验证所需的challenge
click.register(null, function (err, data) {
if (err) {

if (!data.success) {
// 进入 failback,如果一直进入此模式,请检查服务器到极验服务器是否可访问

// 为以防万一,你可以选择以下两种方式之一:

// 1. 继续使用极验提供的failback备用方案
req.session.fallback = true;

// 2. 使用自己提供的备用方案
// todo
} else {
// 正常模式
req.session.fallback = false;

Notice:status indicates captcha initialization. Status=1 refers to successful initialization, status=0 refers to downtime. Please store the status, since it will be needed in secondary verification. In the demo above, session has been used to store status.

Secondary verification (API2), including uptime and downtime

app.post("/gt/validate-click", function (req, res) {
// 对ajax提供的验证凭证进行二次验证
click.validate(req.session.fallback, {
geetest_challenge: req.body.geetest_challenge,
geetest_validate: req.body.geetest_validate,
geetest_seccode: req.body.geetest_seccode
}, function (err, success) {
if (err) {
// 网络错误
status: "error",
info: err

} else if (!success) {
// 二次验证失败
status: "fail",
info: '登录失败'
} else {
status: "success",
info: '登录成功'

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

Install the dependencies with npm install, then run npm start in the SDK root folder.

To view the demo, please visit​ http://localhost:9977 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 process 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 has been passed correctly.
  5. Please provide challenge to our service team. They could help you to check the log.