Server

Overview

Item	Description
Product Name	GeeTest CAPTCHA v4
Developer	Wuhan Jiyi Network Technology Co., Ltd.
Main Function	The latest generation of CAPTCHA offers smarter solutions to address business losses and security risks caused by automated script/bot attacks.
Privacy Policy	GeeTest CAPTCHA v4 Privacy Policy
Compliance Guide	GeeTest CAPTCHA v4 Compliance Guide
Resource Links	C# https://github.com/GeeTeam/gt4_csharp_aspnetcoremvc_demo Golang https://github.com/GeeTeam/gt4_golang_demo Java https://github.com/GeeTeam/gt4-java-demo Node https://github.com/GeeTeam/gt4_node_express_demo Php https://github.com/GeeTeam/gt4-php-demo Python https://github.com/GeeTeam/gt4-python-demo Ruby https://github.com/GeeTeam/gt4-ruby-demo

This page will show you how to deploy GeeTest CAPTCHA V4 with the mainstream back-end coding languages.

The demo list in different back-end languages

Language	address
C#	https://github.com/GeeTeam/gt4_csharp_aspnetcoremvc_demo
Golang	https://github.com/GeeTeam/gt4_golang_demo
Java	https://github.com/GeeTeam/gt4-java-demo
Node	https://github.com/GeeTeam/gt4_node_express_demo
PhP	https://github.com/GeeTeam/gt4-php-demo
Python	https://github.com/GeeTeam/gt4-python-demo
Ruby	https://github.com/GeeTeam/gt4-ruby-demo

Secondary validation API

Interface information	Description
API address	http://gcaptcha4.geetest.com/validate
Supported protocol	http/https
Request method	GET/POST
Content type	application/x-www-form-urlencoded
Response format	json

Request parameters

Parameter Name	Type	Description
lot_number	string	Verify serial number
captcha_output	string	Verify output information
pass_token	string	Token of the verification
gen_time	string	Timestamp of the verification
captcha_id	string	CAPTCHA ID
sign_token	string	Verification signature

Response parameters

Generally, it only needs to deal with the return value when the verification succeeds and the verification fails. Also, the abnormal return value only occurs when the client does not request the correct method.

1 Example of successful verification return

{
    "status": "success",  //request status
    "result": "success",  //the result of secondary verification
    "reason": "",  // the explaination of result
    "captcha_args": {  // verify the output parameters
        "used_type": "slide", 
        "user_ip": "127.0.0.1", 
        "lot_number": "4dc3cfc2cdff448cad8d13107198d473", 
        "scene": "反爬虫 anti crawler", 
        "referer": "http://127.0.0.1:8077/"
        // ...
    }
}

2 Example of validation failure return

{
    "status": "success",  //request status
    "result": "fail",  //the result of secondary verification
    "reason": "pass_token expire",  // the explaination of result
    "captcha_args": {  // verify the output parameters
        ...
    }
}

3 Example of request exception return

{
    "status": "error",  //request status
    "code": "-50005",  // error code
    "msg": "illegal gen_time",  // error message
    "desc": {  // error description
        "type": "defined error"
    }
}

Here is an example in Python:

def post(self):
    # 1. Initialize GeeTest parameter information
    captcha_id = '647f5ed2ed8acb4be36784e01556bb71'
    captcha_key = 'b09a7aafbfd83f73b35a9b530d0337bf'
    api_server = 'http://gcaptcha4.geetest.com'

    # 2. Get the verification parameters passed from the front end after user verification  
    lot_number = self.get_argument('lot_number', '')
    captcha_output = self.get_argument('captcha_output', '')
    pass_token = self.get_argument('pass_token', '')
    gen_time = self.get_argument('gen_time', '')

     # 3. Generate signature
     # Using standard hmac algorithms to generate signatures, using the user's current verification serial number lot_number as the original message, and the client's verification private key as the key
     # Using sha256 hash algorithm to hash message and key in one direction to generate the final signature
    lotnumber_bytes = lot_number.encode()
    prikey_bytes = captcha_key.encode()
    sign_token = hmac.new(prikey_bytes, lotnumber_bytes, digestmod='SHA256').hexdigest()

     # 4. Upload verification parameters to the second verification interface of GeeTest to verify the user verification status
     query = {
        "lot_number": lot_number,
        "captcha_output": captcha_output,
        "pass_token": pass_token,
        "gen_time": gen_time,
        "sign_token": sign_token,
     }

     # captcha_idParameter is recommended to be placed after url, so that when an exception is requested, it can be quickly located in the log according to the id
     url = api_server + '/validate' + '?captcha_id={}'.format(captcha_id)

     # Pay attention to handling interface exceptions, and make corresponding exception handling when requesting GeeTest secondary verification interface exceptions or response status is not 200
     # Guarantee that the business process will not be blocked by interface request timeout or service non-response
     try:
         res = requests.post(url, query)
         assert res.status_code == 200
         gt_msg = json.loads(res.text)
     except Exception as e:
        gt_msg = {'result': 'success', 'reason': 'request geetest api fail'}

        # 5. According to the user authentication status returned by GeeTest, the website owner conducts his own business logic
        if gt_msg['result'] == 'success':
            self.write({'login': 'success', 'reason': gt_msg['reason']})
        else:
            self.write({'login': 'fail', 'reason': gt_msg['reason']})