Online Fraud Detection API

This tool is designed to help prevent online fraud with credit card. It compares the transaction shipping / billing information with IP geolocation data for all countries. For USA and Canada, the API also confirm area code and postal/zip code information. It is very flexible, parameters weight (how it influence the final fraud score) can be set manually. Here are 2 screenshots taken from a live store : good transaction and fraudulent transaction. The API only ask "incomplete" data about the transaction to respect privacy.

If you are looking for XML-based web service solution, please visit FraudLabs.com for more information.

Try our new fraud prevention solution! FREE Micro Plan available for up to 500 transactions per month. Please visit us at FraudLabsPro.com for details.

API usage

http://api.ipinfodb.com/v2/fraud_query.php?key=<your_api_key>&ip=74.125.45.100&country_code=us&district=94043&area_code=650&mail_domain=ipinfodb.com&city=Mountain+View

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Errors></Errors>
<Warnings></Warnings>
<Messages></Messages>
<DistrictCity>Mountain View</DistrictCity>
<IpCountryCode>US</IpCountryCode>
<IpCountry>United States</IpCountry>
<IpRegionCode>06</IpRegionCode>
<IpRegion>California</IpRegion>
<IpCity>Mountain View</IpCity>
<Score>100</Score>
<AccuracyScore>100</AccuracyScore>
<ScoreDetails>Postal/zip code city : Mountain View, supplied city : Mountain View, match score : 100 | Distance between IP and shipping city : 2 KM | Shipping country : US, IP address country : US | Shipping district city : Mountain View, IP address city : Mountain View, match score : 100 | IP area code : 650, supplied area code : 650 | Postal/zip code area code : 650, supplied area code : 650 | Mail domain is NOT from a free email provider | IP address NOT in the Spamhaus database | ip_country_match test success. Added 10 points | areacode_ip_match test success. Added 3 points | areacode_district_match test success. Added 4 points | city_district_match test success. Added 4 points | ip_city_distance test success. Added 3 points | ip_city_match test success. Added 2 points | spamhaus test success. Added 2 points | freemail test success. Added 1 points | Accuracy score : 29 points on 29 possible points | Final score : 29 on 29</ScoreDetails>
</Response>

Interpreting results

The "Score" in the XML answer is the score, in percent, the query had on all tests that were passed. Higher the score is, less chances it's a fraudulent transaction. The "AccuracyScore" is the score, in percent, the query you sent has over the total possible tests.

http://api.ipinfodb.com/v2/fraud_query.php?key=<your_api_key>&ip=74.125.45.100&country_code=us

It's a very good idea to read "ScoreDetails" for the first queries to understand exactly how the API is working. Ajusting parameters weight according to your needs is also a good thing to do. We don't want to give exact rules as what score is good or not since it all depends on the product and market. From our experience, transaction score between 70 and 100% is good and below 50% there is good chances it's fraud. If you feel the API answer is in a grey zone, we strongly suggest that you investigate the transaction by other means (calling the customer, calling the card company, etc).

Parameters weight

Parameters weight is simply a way to give more weight in the score to certain parameters. Setting weight to parameters is optionnal since they all have default values (see parameter table). For example, a parameter with a weight of 15 will affect 3 time more the score than a parameter with a weight of 5. Total points in that example would be 20, the first parameter would count for 15 while the second one only for 5.

Input the data in your application

<?php
 
function fraudQuery($ip, $country_code, $district, $city, $area_code, $mail_domain){
 
$d = file_get_contents("http://api.ipinfodb.com/v2/fraud_query.php?key=<your_api_key>&ip=$ip&country_code=$country_code&district=$district&city=$city&area_code=$area_code&mail_domain=$mail_domain");
//Use backup server if cannot make a connection
if (!$d){
$backup = file_get_contents("http://backup.ipinfodb.com/fraud_query.php?key=&lt;your_api_key&gt;&ip=$ip&country_code=$country_code&district=$district&city=$city&area_code=$area_code&mail_domain=$mail_domain&enable_hostname=1");
$backup = utf8_encode($d);
$enc = mb_detect_encoding($backup);
$backup = mb_convert_encoding($d, 'UTF-8', $enc);
$answer = new SimpleXMLElement($backup);
if (!$backup) return false; // Failed to open connection
}else{
$d = utf8_encode($d);
$enc = mb_detect_encoding($d);
$d = mb_convert_encoding($d, 'UTF-8', $enc);
$answer = new SimpleXMLElement($d);
}
 
 
return array('Errors' => $answer->Errors, 'Warnings' => $answer->Warnings, 'Messages' => $answer->Messages, 'DistrictCity' => $answer->DistrictCity, 'IpCountryCode' => $answer->IpCountryCode, 'IpCountry' => $answer->IpCountry, 'IpRegionCode' => $answer->IpRegionCode, 'IpRegion' => $answer->IpRegion, 'IpCity' => $answer->IpCity, 'IpHostName' => $answer->IpHostName, 'Score' => $answer->Score, 'AccuracyScore' => $answer->AccuracyScore, 'ScoreDetails' => $answer->ScoreDetails);
 
}
 
$fraud_query = fraudQuery('74.125.45.100', 'us', '94043', 'Mountain+View', '650', 'ipinfodb.com');
 
echo "Errors : " . $fraud_query['Errors'] . "\n";
echo "Warnings : " . $fraud_query['Warnings'] . "\n";
echo "Messages : " . $fraud_query['Messages'] . "\n";
echo "DistrictCity : " . $fraud_query['DistrictCity'] . "\n";
echo "IpCountryCode : " . $fraud_query['IpCountryCode'] . "\n";
echo "IpCountry : " . $fraud_query['IpCountry'] . "\n";
echo "IpRegionCode : " . $fraud_query['IpRegionCode'] . "\n";
echo "IpRegion : " . $fraud_query['IpRegion'] . "\n";
echo "IpCity : " . $fraud_query['IpCity'] . "\n";
echo "IpHostName : " . $fraud_query['IpHostName'] . "\n";
echo "Score : " . $fraud_query['Score'] . "\n";
echo "AccuracyScore : " . $fraud_query['AccuracyScore'] . "\n";
echo "ScoreDetails : " . $fraud_query['ScoreDetails'] . "\n";
 
?>

Why do I need to register?

We are always trying to improve on our free services and to do so we need to be able to tell who is querying what data and how often. This will enable us to fully optimize our limited resources to providing a more stable and reliable service to our users.

What is this API key and do I need it?

This API key is just a random string of characters which uniquely identifies each user. This is how we can track your usage for the purpose of optimizing our resources. Users of our existing APIs need not use this API key but please note that we are in the process of phasing out the old APIs and you will have to use our newer APIs in the future. These new APIs are more optimized for performance and as such we need to be able to allocate resources in an optimal fashion by tracking the usage of the APIs.

How do I get this API key?

This API key is free for everyone. You just have to go to here to register and a unique API key will be sent to your email address.

OSCommerce integration

For easy OSCommerce integration, we wrote a contribution for our API.

Accuracy

The API is given as a tool to detect fraud, all databases used are up to date but we cannot guarantee any accuracy. We leave it up to you to interpret the score result.

Privacy notice

We made this API so that required information is "incomplete" to protect privacy (no specific address, no names, no amount, no credit card info, no full email). Also, we do not store the data that is transmitted to us (either in logs or database).

Servers uptime

We have 2 servers. They are load balanced & highly available (ldirectord + heartbeat setup). Our goal is to have over 99.99% uptime.

Contribute

We would really appreciate any feedbacks or bug reports in the forum.

Query limit

We do not have a specific daily limit but queries that are at a rate faster than 2 per second will be put in "queue". If you stay below 2 queries/second everything will be normal. If you go over the limit, you will still get an answer for all queries but they will be slowed down to about 1 per second.

Keeping in touch for updates

The best way to get updates and news is with our RSS feed or on Twitter