We provide automated access to our minFraud service using the HTTP protocol. There is also a new SOAP interface available. This page describes the input and output fields for the minFraud service. While you can write your own code to access the HTTP service, we recommend using our PHP, Perl, Java and ASP APIs. The APIs will reduce programming time, and automatically failover to the backup server in case the primary server is unreachable.

MaxMind minFraud has been integrated by many popular e-commerce software providers. For more information, please take a look at the list of e-commerce solutions that support minFraud.

For a more detailed description of each feature and its relevance to fraud, please take a look at the fraud detection manual.

minFraud Service Inputs

Field		Description
i	Required	Client IP Address (IP address of customer placing order)
city, region, postal, country	Required	Billing City/State/ZipCode/Country
domain	Optional	E-mail domain (e.g. hotmail.com, aol.com)
bin	Optional	BIN number, first 6 digits of credit card that identifies the issuing bank.
binName	Optional	Name of the bank which issued the credit card based on BIN number. Used to verify that cardholder is in possession of credit card.
binPhone	Optional	Customer service phone number listed on back of credit card. Used to verify that cardholder is in possession of credit card.
custPhone	Optional	Area code and local exchange. Used to verify phone number is in billing location of cardholder. Most formats are acceptable, as we remove non-numeric characters from the input.
license_key	Required	License Key. Obtain my license key or sign up for free trial.
requested_type	Optional	Can be set to city (standard service) premium (premium service) To be used if you have multiple plans in one account and wish to select type of query you wish to make. By default the service uses the highest level available. For example if you have both standard and premium paid queries, the service will return the premium lookup results by default. However, if you wish to make a standard query to save on costs, specify the requested_type parameter to be city.
forwardedIP	Optional	IP address of end user, as forwarded by transparent proxy. Transparent proxies set the HTTP headers X-Forwarded-For or Client-IP, which contain the IP address of the end user. These IP addresses can be typically be accessed through the environment variables HTTP_X_FORWARDED_FOR and HTTP_CLIENT_IP. Note that the forwarded IP should be passed to the forwardedIP input field instead of the i input field, because we check that the IP address passed to the i input field is a legitimate transparent proxy before using the value in the forwardedIP input field.
emailMD5	Optional	MD5 hash in hexadecimal form of lowercase version of e-mail. Used by carderEmail output to check against database of high risk e-mails. Must convert e-mail to lowercase before passing to MD5 hash function. MD5 hash is used to protect privacy of customer while having a unique identifier for the e-mail.
usernameMD5	Optional	MD5 hash in hexadecimal form of lowercase version of your customer's user name. Used by highRiskUsername output to check against database of high risk user names. Must convert user name to lowercase before passing to MD5 hash function.
passwordMD5	Optional	MD5 hash in hexadecimal form of lowercase version of your customer's password. Used by highRiskPassword output to check against database of high risk passwords. Must convert password to lowercase before passing to MD5 hash function.
shipAddr, shipCity, shipRegion, shipPostal, shipCountry	Optional	Shipping address. Used by shipForward output field to check against over 1,600 known mail forwarding services. You should only pass the shipping address when shipping physical goods, and when the billing address and shipping address are different, or an AVS check is not available on the billing address.
txnID	Optional	Internal transaction ID of order. Used to locate queries in our logs for debugging and reporting purposes, and is included in minFraud alert e-mails and notifications.
sessionID	Optional	Internal session ID for website. Used to link fraudulent orders together when carder tries using different credit cards and proxy servers. Typically you would get the session ID by tracking the user with a cookie or URL rewriting.

minFraud Service Outputs

Field	Format	Description
Geographical IP address location checking
countryMatch	Yes or No	Whether country of IP address matches billing address country (mismatch = higher risk)
countryCode	two-letter ISO-3166 code	Country Code of the IP address
highRiskCountry	Yes or No	Whether IP address or billing address country is in Egypt, Ghana, Indonesia, Lebanon, Macedonia, Morocco, Nigeria, Pakistan, Romania, Serbia and Montenegro, Ukraine, or Vietnam.
distance	rounded integer	Distance from IP address to Billing Location in kilometers (large distance = higher risk)
ip_region	two character string ISO-3166-2/FIPS 10-4 code	Estimated State/Region of the IP address, ISO-3166-2/FIPS 10-4 code
ip_city	string	Estimated City of the IP address
ip_latitude	degrees	Estimated Latitude of the IP address
ip_longitude	degrees	Estimated Longitude of the IP address
ip_isp	string	ISP of the IP address
ip_org	string	Organization of the IP address
Proxy Detection
anonymousProxy	Yes or No	Whether IP address is Anonymous Proxy (anonymous proxy = very high risk)
proxyScore	decimal from 0 to 10	Likelihood of IP Address being an Open Proxy
isTransProxy	Yes or No	Whether IP address is in our database of known transparent proxy servers, returned if forwardedIP is passed as an input.
E-mail and Login Checks
freeMail	Yes or No	Whether e-mail is from free e-mail provider (free e-mail = higher risk)
carderEmail	Yes or No	Whether e-mail is in database of high risk e-mails
highRiskUsername	Yes or No	Whether usernameMD5 input is in database of high risk usernames. Only returned if usernameMD5 is included in inputs.
highRiskPassword	Yes or No	Whether passwordMD5 input is in database of high risk passwords. Only returned if passwordMD5 is included in inputs.
Issuing Bank BIN Number Checks
binMatch	Yes, No, NotFound, or NA	Whether country of issuing bank based on BIN number matches billing address country*
binCountry	two-letter ISO-3166 code	Country Code of the bank which issued the credit card based on BIN number*
binNameMatch	Yes, No, NotFound, or NA	Whether name of issuing bank matches inputted binName. A return value of Yes provides a positive indication that cardholder is in possession of credit card.*
binName	string	Name of the bank which issued the credit card based on BIN number*. Available for approximately 96% of BIN numbers.
binPhoneMatch	Yes, No, NotFound, or NA	Whether customer service phone number matches inputed binPhone. A return value of Yes provides a positive indication that cardholder is in possession of credit card.*
binPhone	string	Customer service phone number listed on back of credit card*. Available for approximately 75% of BIN numbers. In some cases phone number returned may be outdated.
Address and Phone Number Checks
custPhoneInBillingLoc	Yes, No, NotFound, or NA	Whether the customer phone number is in the billing zip code. A return value of Yes provides a positive indication that the phone number listed belongs to the cardholder. A return value of No indicates that the phone number may be in a different area, or may not be listed in our database. Currently we only support US Phone numbers.
shipForward	Yes, No, or NA	Whether shipping address is in database of known mail drops
cityPostalMatch	Yes or No	Whether billing city and state match zipcode. Currently available for US addresses only, returns empty string outside the US.
shipCityPostalMatch	Yes or No	Whether shipping city and state match zipcode. Currently available for US addresses only, returns empty string outside the US.
Risk Score
score	decimal from 0 to 10	Overall fraud score based on outputs listed above. This is the original fraud score, and is based on a simple formula. It has been replaced with riskScore (see below), but is kept for backwards compatibility.
explanation	string	A brief explanation of the score, detailing what factors contributed to it, according to our formula
riskScore	decimal from 0 to 100	New fraud score representing the estimated probability that the order is fraud, based off of analysis of past minFraud transactions. Requires an upgrade for clients who signed up before February 2007.
Account Information
queriesRemaining	integer	Number of queries remaining in your account, can be used to alert you when you may need to add more queries to your account
maxmindID	eight character string	Unique identifier, used to reference transactions when reporting fraudulent activity back to MaxMind. This reporting will help MaxMind improve its service to you and will enable a planned feature to customize the fraud scoring formula based on your chargeback history.
err	string	Returns an error string with a warning message or a reason why the request failed. List of possible error strings.

String outputs can be up to 255 characters long.
* Only Premium service returns binCountry, binName and binPhone.

minFraud Service URLs
Secure (HTTPS)

• Primary Server: https://minfraud1.maxmind.com/app/ccv2r
• Backup Server: https://minfraud2.maxmind.com/app/ccv2r

• Primary Server: http://minfraud1.maxmind.com/app/ccv2r
• Backup Server: http://minfraud2.maxmind.com/app/ccv2r