Backend: Query the API

Warning

API version 1 is now deprecated. It will be supported for the foreseeable future, however any new implementations should use the improved version 2 API.

Validation API

To ensure that all checks have been passed and not circumvented we assign a token to each user. This token must be checked before a payment is processed. When the final confirmation has been clicked by a user, Empello will pass a token either via a form or by placing a cookie. A call must be made to Empello's token api referencing this token and the api key provided. It will reply with a boolean variable is_valid, true for valid and false for invalid. If the token is invalid then the payment must not be accepted.

Warning

You must store the token alongside the transaction for audit purposes.

The POST request sent to https://antifraud.empello.net/api/v1/token/validate/ should be sent as form-data. Here is an example cURL command (please note these are only example values):

    curl -X POST \
    https://antifraud.empello.net/api/v1/token/validate/ \
    -F api_key=JYAguvWE6Fn4wRmXPkY9kaAiD \
    -F timestamp=2022-12-31T12:59:59.000Z \
    -F user_ip=123.123.123.123 \
    -F 'user_agent=Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Mobile Safari/537.3' \
    -F token=njgxydsxrogqgioblcrkolllrbgbmkhphykypupahkclhzztnhzygqrotxlrjwrz

For code examples of this cURL see here.

The endpoint will reply with the token and it's verification status. An accepted transaction (that is is_valid = true) looks like this:

    {"is_valid": true,
    "timestamp": "2018-12-31T12:59:59+00:00",
    "token": "bQzBYxvHNguXHhLMWiikEUHkQhmt2fxpT8fkJqaB7ddMoGGpEY6Hm3c2avH9G4mc",
    "status": 200}

For a blocked transaction the reply will look like this:

    {"is_valid": False,
    "threat_code": 16,
    "threat_flags": "BOT_ACTIVITY",
    "token": "njgxydsxrogqgioblcrkolllrbgbmkhphykypupahkclhzztnhzygqrotxlrjwrz",
    "status": 200,
    "timestamp": 2019-03-14T16:19:53.389721}

Warning

If you are seeing Suspicious Token as a block reason in implementation testing then please see the troubleshooting page.

Note

Threat flags are separated by a #!|, for a full list of threat codes and flags visit the threat codes reference.

Code examples

Feel free to use the examples below to implement the API query on your backend. Remember to replace YOUR_API_KEY with the API key given to you by Empello (if you do not have one please contact us) and replace YOUR_TOKEN with the token to be queried.

Java

CloseableHttpClient httpclient = HttpClients.createDefault();
HttpPost httpPost = new HttpPost("https://antifraud.empello.net/api/v1/token/validate/");
httpPost.setHeader("Content-type", "application/x-www-form-urlencoded; charset=UTF-8");

List<NameValuePair> params = new ArrayList<NameValuePair>();
params.add(new BasicNameValuePair("api_key", "YOUR_API_KEY"));
params.add(new BasicNameValuePair("timestamp", DateTimeFormatter
        .ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSSSS")
        .withZone(ZoneOffset.UTC)
        .format(Instant.now())));
params.add(new BasicNameValuePair("user_ip", getUserIP()));
params.add(new BasicNameValuePair("user_agent", getUserAgent()));
params.add(new BasicNameValuePair("token", "YOUR_TOKEN"));

httpPost.setEntity(new UrlEncodedFormEntity(params, "UTF-8"));

ResponseHandler<String> responseHandler = response -> {
    HttpEntity entity = response.getEntity();
    return entity != null ? EntityUtils.toString(entity) : null;
};

String responseBody = httpclient.execute(httpPost, responseHandler);
JSONObject responseObj = new JSONObject(responseBody);

if (responseObj.has("message")) {
    System.out.println("Message: " + responseObj.get("message"));
} else {
    System.out.println("Status:           " + responseObj.get("status"));
    System.out.println("Token:            " + responseObj.get("token"));
    System.out.println("Timestamp:        " + responseObj.get("timestamp"));
    System.out.println("IsValid:          " + responseObj.get("is_valid"));
    System.out.println("ThreatCode:       " + responseObj.get("threat_code"));
    System.out.println("ThreatFlags:      " + responseObj.get("threat_flags"));
    System.out.println("HasAllDatapoints: " + responseObj.get("has_all_datapoints"));
}

Kotlin

val url = URL("https://antifraud.empello.net/api/v1/token/validate/")
val conn: HttpURLConnection = url.openConnection() as HttpURLConnection
conn.requestMethod = "POST"

val arguments: MutableMap<String, String> = HashMap()
arguments["api_key"] = "YOUR_API_KEY"
arguments["timestamp"] = DateTimeFormatter
    .ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSSSS")
    .withZone(ZoneOffset.UTC)
    .format(Instant.now())
arguments["user_ip"] = getUserIP()
arguments["token"] = "YOUR_TOKEN"
arguments["user_agent"] = getUserAgent()

val sj = StringJoiner("&")
for ((key, value) in arguments) sj.add(
    URLEncoder.encode(key, "UTF-8") + "=" + URLEncoder.encode(value, "UTF-8")
)
val out: ByteArray = sj.toString().toByteArray()
val length = out.size

conn.doInput = true
conn.doOutput = true

conn.setFixedLengthStreamingMode(length)
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded; charset=UTF-8")
conn.connect()
conn.outputStream.use { os -> os.write(out) }

val response: String
if (conn.responseCode == 200) {
    response = conn.inputStream.bufferedReader().readText()
    val responseObj = JSONObject(response)

    println("Status:           " + responseObj.get("status"))
    println("Token:            " + responseObj.get("token"))
    println("Timestamp:        " + responseObj.get("timestamp"))
    println("IsValid:          " + responseObj.get("is_valid"))
    println("ThreatCode:       " + responseObj.get("threat_code"))
    println("ThreatFlags:      " + responseObj.get("threat_flags"))
    println("HasAllDatapoints: " + responseObj.get("has_all_datapoints"))

} else {
    response = conn.errorStream.bufferedReader().readText()
    val responseObj = JSONObject(response)

    println("Message: " + responseObj.get("message"))
}

PHP

<?php
function getUserIP()
{
    if (!empty($_SERVER['HTTP_CLIENT_IP'])) {
        $ip = $_SERVER['HTTP_CLIENT_IP'];
    } elseif (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
        $ip = $_SERVER['HTTP_X_FORWARDED_FOR'];
    } else {
        $ip = $_SERVER['REMOTE_ADDR'];
    }
    return $ip;
}

$postdata = http_build_query(
    array(
        'api_key' => "YOUR_API_KEY",
        'timestamp' => date('Y-m-d\TH:i:s.ZZZZZZ', time()),
        'user_ip' => getUserIP(),
        'token' => 'YOUR_TOKEN',
        'user_agent' => $_SERVER['HTTP_USER_AGENT'],
    )
);

$options = array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-type: application/x-www-form-urlencoded",
        'content' => $postdata,
        // We ignore errors, because we also want to parse the body of 400 errors
        'ignore_errors' => '1',
    ),
);

$context = stream_context_create($options);

$api_json = @file_get_contents("https://antifraud.empello.net/api/v1/token/validate/", false, $context);
$api_data = json_decode($api_json, true);

?>

<?php if (isset($api_data['message'])) {?>

    <b>message:</b>             <?php print $api_data['message'];?><br>

<?php } else {?>

    <b>status:</b>             <?php print $api_data['status'];?> <br>
    <b>token:</b>              <?php print $api_data['token'];?> <br>
    <b>timestamp:</b>          <?php print $api_data['timestamp'];?> <br>
    <b>is_valid:</b>           <?php print $api_data['is_valid'] ? 'true' : 'false';?> <br>
    <b>threat_code:</b>        <?php print $api_data['threat_code'];?> <br>
    <b>threat_flags:</b>       <?php print $api_data['threat_flags'];?> <br>
    <b>has_all_datapoints:</b> <?php print $api_data['has_all_datapoints'];?> <br>

<?php }?>

JavaScript

const request = require('request');

const queryEmpelloToken = (params) => {
  return new Promise((resolve) => {
    request.post(
      'https://antifraud.empello.net/api/v1/token/validate/',
      { form: params },
      (error, response, body) => {
        const jsonBody = error ? null : JSON.parse(body);
        resolve({ error, response, body: jsonBody });
      }
    );
  });
};

const getUserIP = (req) => {
  if (req.header('client-ip')) {
    return req.header('client-ip');
  }
  if (req.header('x-forwarded-for')) {
    const forwardedIPs = req.header('x-forwarded-for');
    return forwardedIPs.split(',')[0];
  }
  return req.connection.remoteAddress;
};

const getUserAgent = (req) => {
  return req.header('user-agent');
};

app.get('/', async (req, res) => {
  const { error, body } = await queryEmpelloToken({
    api_key: 'YOUR_API_KEY',
    timestamp: new Date().toISOString(),
    token: 'YOUR_TOKEN',
    user_ip: getUserIP(req),
    user_agent: getUserAgent(req),
  });

  if (error) {
    return res.send(error);
  }

  if (body && body.message) {
    return res.send(body.message);
  }

  const {
    status,
    token,
    timestamp,
    is_valid,
    threat_code,
    threat_flags,
    has_all_datapoints,
  } = body;

  res.send(`
    <b>status:</b>             ${status} <br/>
    <b>token:</b>              ${token} <br/>
    <b>timestamp:</b>          ${timestamp} <br/>
    <b>is_valid:</b>           ${!!is_valid} <br/>
    <b>threat_code:</b>        ${threat_code} <br/>
    <b>threat_flags:</b>       ${threat_flags} <br/>
    <b>has_all_datapoints:</b> ${has_all_datapoints} <br/>
  `);
});

TypeScript

import * as request from "request";

const getUserIP = () => {
  return "1.2.3.4";
};

const getUserAgent = () => {
  return "MY_USER_AGENT";
};

request.post(
  "https://antifraud.empello.net/api/v1/token/validate/",
  {
    form: {
      api_key: 'YOUR_API_KEY',
      timestamp: new Date().toISOString(),
      token: 'YOUR_TOKEN',
      user_ip: getUserIP(),
      user_agent: getUserAgent(),
    },
  },
  (error, _, body) => {
    const jsonBody = error ? null : JSON.parse(body);

    if (error) {
      console.log(error);
      return;
    }

    if (jsonBody && jsonBody.message) {
      console.log(jsonBody.message);
      return;
    }

    const {
      status,
      token,
      timestamp,
      is_valid: isValid,
      threat_code: threatCode,
      threat_flags: threatFlags,
      has_all_datapoints: hasAllDatapoints,
    } = jsonBody;

    console.log(`
      status:              ${status}
      token:               ${token}
      timestamp:           ${timestamp}
      is_valid:            ${!!isValid}
      threat_code:         ${threatCode}
      threat_flags:        ${threatFlags}
      has_all_datapoints:  ${hasAllDatapoints}
    `);
  }
);