validateToken verification API

This document contains descriptions of interfaces:

The validateToken verification interface is used to verify whether the token returned by the front-end is valid (Required)

Interface description

Customers must call the verification endpoint to validate the Captcha response from their service of the backend. The captcha response must only be considered valid once it has been verified by the verification endpoint. The presence of a validateToken alone is not enough to verify it as it does not protect from replay or forgery attacks.

So, after completing the validation of the captcha on the front-end, the user will get the validateToken. The validateToken should be passed to the server following the business request (sign-up|sign-in|...). At this time, you need to invoke the Tongdun interface on your backend service to validate the validateToken.

API

POST ParameterTypeRequired/OptionalDescription
partner_codeStringRequiredpartner code, assigned by TD
partner_keyStringRequiredpartner secret key, assigned by TD
validate_tokenStringRequiredvalidateToken is submitted by the client (urlencode is required as it contains special characters)
black_boxStringRequiredthe blackbox data of the fingerprinter of TD, it will be passed as soon as it is obtained, and the "" string will be passed if it is not obtained (urlencode is required as it contains special characters)
  • Response:
OutputTypeDescription
successBooleanIt always contains a success property, either true or false, indicating whether the operation was successful or not.
statusCodeIntergestatus code of the request
failMesStringerror description of the request
validateResultBooleanthe result of validateToken verification: true | false
  • Description of the status code :
CodeDescriptionAction
200request successtodo
100invalid parameterplease check whether the parameter is passed in according to the API document
600the validateToken is not URLEncode processedplease check whether the parameter validateToken has urlencode (refer to the example)
601failed to decrypt validateTokenplease check whether the value of the parameter validateToken is consistent with the value of the front-end callback method
602validateToken expirationplease check whether the verification time exceeds 10 minutes
603environment verification errorplease check whether the integration environment of the client is consistent with the API environment
604invalid validateTokenplease check whether the validateToken has been used
605abnormal devicefind error when validate the device information
606abnormal partnerplease check whether the partner passed by the sdk of the integration is consistent with the partner_code of the post parameter
500service erroryou can provide the detail of the response for further check

In case of a successful validation, the response should be similar to the following:

{
   "success": true,
   "statusCode": 200,
   "failMes": "",
   "validateResult": true
}

In case of a validation failure, the response should be similar to the following:

{
   "success": false,
   "statusCode": 100,
   "failMes": "illegal parameter",
   "validateResult": false
}

Server-side Example

Java Example

The following example code shows how to invoke the API service through Java native HttpClient

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import javax.net.ssl.HttpsURLConnection;
import javax.net.ssl.SSLSocketFactory;
import java.io.BufferedOutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;
public class FraudApiInvoker {

       private final Log log = LogFactory.getLog(this.getClass());
       private static final String apiUrl = "https://api.tongdun.cn/sphinx/validatetoken/v2";

       public static void main(String[] args) {
           Map<String, Object> params = new HashMap<String, Object>();
           params.put("partner_code", "XXX");
           params.put("partner_key", "XXX");
           params.put("validate_token", "XXX");
           params.put("black_box", "XXX");
           String apiResp = new FraudApiInvoker().invoke(params);
           if (apiResp != null) {
               // todo business logic
               System.out.println(apiResp);
           } else {
               // handle connection timeout or other exceptions.It is not recommended to directly treat it as a verification failure
           }
       }

       public String invoke(Map<String, Object> params) {
           try {
               URL url = new URL(apiUrl);
               // request parameters
               StringBuilder postBody = new StringBuilder();
               for (Map.Entry<String, Object> entry : params.entrySet()) {
                   if (entry.getValue() == null) continue;
                   // UrlEncode
 postBody.append(entry.getKey()).append("=").append(URLEncoder.encode(entry.getValue().toString(), "utf-8")).append("&");
               }

               if (!params.isEmpty()) {
                   postBody.deleteCharAt(postBody.length() - 1);
               }

               SSLSocketFactory ssf = (SSLSocketFactory) SSLSocketFactory.getDefault();
               HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();
               conn.setSSLSocketFactory(ssf);
               conn.setRequestProperty("Connection", "Keep-Alive");
               conn.setConnectTimeout(1000);
               conn.setReadTimeout(1000);
               conn.setRequestMethod("POST");
               conn.setDoOutput(true);
               BufferedOutputStream outputStrm = new BufferedOutputStream(conn.getOutputStream());
               outputStrm.write(postBody.toString().getBytes());
               outputStrm.flush();
               outputStrm.close();
               int responseCode = conn.getResponseCode();
               if (responseCode != 200) {
                   log.warn("[FraudApiInvoker] invoke failed, response status:" + responseCode);
                   return null;
               }
               BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
               StringBuilder result = new StringBuilder();
               String line;
               while ((line = bufferedReader.readLine()) != null) {
                   result.append(line).append("\n");
               }
               return result.toString().trim();
           } catch (Exception e) {
               log.error("[FraudApiInvoker] invoke throw exception, details: " + e);
           }
           return null;
       }
   }

Servlet example

public class ValidateTokenVerify extends HttpServlet {
   @Override
   protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
       String blackBox =  req.getParameter("blackBox");
       String validateToken = req.getParameter("validateToken");
       Map params = new HashMap();
       params.put("partner_code", ""); 
       params.put("partner_key", ""); 
       params.put("black_box", blackBox); 
       params.put("validate_token", validateToken);
       String apiJsonResp = new FraudApiInvoker().invoke(params);
   }
}