Dev Home
minFraud
GeoIP
Proxy Detection
FAQ
Main Site

minFraud Web Service API

Client APIs
HTTP API
- Input
  - Required Fields
  - Shipping Address
  - User Data
  - BIN-related
  - Transaction Linking
  - Transaction Information
  - Credit Card Check
  - Miscellaneous
- Output
  - Risk Score
  - GeoIP Location Checks
  - Proxy Detection
  - Emails and Login Checks
  - Bank Checks
  - Address and Phone Number Checks
  - Account Information Fields
  - Error Reporting
SOAP API

The minFraud web service is available using a simple URI-based API or via SOAP. To use this service, you must have a valid MaxMind license key.

Client APIs

We encourage you to use one our minFraud client APIs if possible. APIs are available in the following languages:

ASP
Java
Perl
PHP

The client APIs take care of formatting requests and parsing the response for you.

HTTP API

If an API for your language is not available, you can use the "raw" API detailed below.

The HTTP API requires you to pass a set of parameters as an HTTP GET or POST. Results are returned in a simple text format documented below.

The URI for this service is https://minfraud.maxmind.com/app/ccv2r.

The minfraud.maxmind.com hostname automatically picks the data center geographically closest to you. In some cases, this data center may not be the one that provides you with the best service. You can explicitly try the minfraud-us-east.maxmind.com and minfraud-us-west.maxmind.com hostnames to see which one provides the best performance for you.

Input

The minFraud API accepts input in a query string or as a form post (application/x-www-form-urlencoded). It accepts the following fields. The name of each field should be used as the query string or form field name. Field names are case-sensitive.

The length of the data passed to us does not matter for most fields. We will truncate inputs as needed. However, for a few fields the length is important, and this is noted in the table below.

Name	Type (length)	Description
Required Fields The following fields are required.
i	string	The IP address of the customer placing the order. This should be passed as a string like "44.55.66.77" or "2001:db8::2:1".
city	string	The billing city for the customer.
region	string	The billing region/state for the customer.
postal	string	The billing postal (zip) code for the customer.
country	string	The billing country for the customer. This can be passed as the full country name or as an ISO 3166 code.
license_key	string	Your MaxMind license key.
Shipping Address These fields are used to check against our database of known high risk shipping addresses. You should only pass these fields when shipping physical goods.
shipAddr	string	The shipping street address.
shipCity	string	The shipping address city.
shipRegion	string	The shipping address region/state.
shipPostal	string	The shipping address postal (zip) code.
shipCountry	string	The shipping address country.
User Data Some of these fields are MD5 hash fields. Such fields should be passed as an MD5 hash in hex form. Always lower-case the input before hashing. Do not use any salt when hashing these inputs.
domain	string	The domain for the user's email address. This field should not be hashed.
custPhone	string	The customer's phone number, including area code and local exchange. This is used to verify that the customer's phone number is in the same billing location as the cardholder. Most formats are acceptable. We strip out all non-numeric characters from the input.
emailMD5	string (32)	An MD5 hash of the user's email address.
usernameMD5	string (32)	An MD5 hash of the user's username.
passwordMD5	string (32)	An MD5 hash of the user's password.
BIN-related These fields are used to verify that the customer is in possession of the credit card.
bin	string	The credit card BIN number. This is the first 6 digits of the credit card number. It identifies the issuing bank.
binName	string	The name of the bank which issued the credit card, based on the BIN number. This is used to verify that cardholder is in possession of credit card. You must set the bin field if you set this one.
binPhone	string	The customer service phone number listed on the back of the credit card. This is used to verify that cardholder is in possession of credit card. You must set the bin field if you set this one.
Transaction Linking These fields are used to link together fraudulent orders from the same browser across multiple proxies or credit card numbers.
sessionID	string	Your internal session id.
user_agent	string	The User-Agent HTTP header.
accept_language	string	The Accept-Language HTTP header.
Transaction Information These fields provide additional information about the transaction.
txnID	string	Your internal transaction id for the order. We can use this to locate a specific transaction in our logs, and it will also show up in email alerts and notifications from us to you.
order_amount	decimal (20, 3)	The customer's order amount.
order_currency	string (3)	The currency used for the customer's order as an ISO 4217 code.
shopID	string	Your internal id for the shop, affiliate, or merchant this order is coming from.
txn_type	enum	The transaction type. This can be set to one of the following strings: creditcard debitcard paypal google - Google checkout other lead - lead generation survey - online survey sitereg - site registration The lead, survey, and sitereg types are used for non-purchase transactions.
Credit Card Check To provide these fields you must run the AVS and/or CVV checks before calling minFraud.
avs_result	enum	The AVS check result, as returned to you by the credit card processor. The minFraud service accepts the following codes: N - no match Y - complete match A - partial match, address only P - partial match, postal code only
cvv_result	enum	The CVV check result. This should be either "N" or "Y". Do not pass the CVV code itself.
Miscellaneous
requested_type	enum	This can be set to either "standard" or "premium". By default, we use the highest level of service available for your account. If you have both the premium and standard minFraud service, you can choose to use the standard service to save on costs.
forwardedIP	string	The end user's IP address, as forwarded by a transparent proxy. Transparent proxies set the HTTP headers X-Forwarded-For or Client-IP to the IP address of the end user. This should be passed as a string like "44.55.66.77" or "2001:db8::2:1". Note that the forwarded IP should not be set in the i field. 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.

Output

The minFraud service returns it's output as a set of fields separated by semi-colons (;). Each field consists of a name and value separated by an equals sign (=). The field values are not escaped, but will never contain a semi-colon or equals sign.

All strings are returned in the ISO-8859-1 encoding. This encoding is also referred to as latin1.

Here is an example of the output with just a few fields:

riskScore=13.2;distance=6;countryMatch=Yes;countryCode=US;freeMail=Yes

The API version column indicates in what version of the API a field was added. You can explicitly ask for responses in older API formats. By default, all new users will receive responses for the version that was current when they signed up for the service. The latest version is 1.3.

Name	Type (length)	Description	API version
Risk Score
riskScore	decimal	This field contains the risk score, from 0.01 to 100. A higher score indicates a higher risk of fraud. For example, a score of 20 indicates a 20% chance that a transaction is fraudulent. We never return a risk score of 0, since all transactions have the possibility of being fraudulent.	1.1
score	decimal	This field has been deprecated and is no longer present in API version 1.3. This is an older version of the risk score, ranging from 0 to 10.	1.0
explanation	string	This field has been deprecated and is no longer present in API version 1.3. This is a brief explanation of the score (not the riskScore).	1.0
GeoIP Location Checks These fields are based on the correspondance between the user's IP address and the location information they provided.
countryMatch	enum	This field can be either Yes or No. It indicates whether the country of the IP address matched the billing address country. A mismatch indicates a higher risk of fraud.	1.0
highRiskCountry	enum	This field can be either Yes or No. It indicates whether the country is one that MaxMind considers to be especially risky, such as Ghana, Nigeria, or Vietnam.	1.0
distance	integer	The distance from the IP address location to the billing location, in kilometers. A higher distance indicates a higher risk of fraud.	1.0
ip_accuracyRadius	integer	The radius in kilometers around the specified location where the IP address is likely to be.	1.2
ip_city	string	The city or town name associated with the IP address. See our list of cities to see all the possible return values. This list is updated on a regular basis.	1.0
ip_region	string (2)	A two character ISO-3166-2 or FIPS 10-4 code for the state/region associated with the IP address. For the US and Canada, we return an ISO-3166-2 code. In addition to the standard ISO codes, we may also return one of the following: AA - Armed Forces America AE - Armed Forces Europe AP - Armed Forces Pacific We return a FIPS code for all other countries. We provide a CSV file which maps our region codes to region names. The columns are ISO country code, region code (FIPS or ISO), and the region name.	1.0
ip_regionName	string	The region name associated with the IP address.	1.2
ip_postalCode	string	The postal code associated with the IP address. These are available for some IP addresses in the Australia, Canada, France, Germany, Italy, Spain, Switzerland, United Kingdom, and the US. We return the first 3 characters for Canadian postal codes. We return the the first 2-4 characters (outward code) for postal codes in the United Kingdom.	1.2
ip_metroCode	integer	The metro code associated with the IP address. These are only available for IP addresses in the US. MaxMind returns the same metro codes as the Google AdWords API.	1.2
ip_areaCode	string	The telephone area code associated with the IP address. These are only available for IP addresses in the US. This output is deprecated, and may not reflect newer area codes.	1.2
countryCode	string (2)	A two-character ISO 3166-1 country code for the country associated with the IP address. In addition to the standard codes, we may also return one of the following: A1 - an anonymous proxy. A2 - a satellite provider. EU - an IP in a block used by multiple European countries. AP - an IP in a block used by multiple Asia/Pacific region countries. The US country code is returned for IP addresses associated with overseas US military bases.	1.0
ip_countryName	string	The country name associated with the IP address.	1.2
ip_continentCode	string (2)	A two-character code for the continent associated with the IP address. The possible codes are: AF - Africa AS - Asia EU - Europe NA - North America OC - Oceania SA - South America	1.2
ip_latitude	decimal	The latitude associated with the IP address.	1.0
ip_longitude	decimal	The longitude associated with the IP address.	1.0
ip_timeZone	string	The time zone associated with the IP address. Time zone names are taken from the IANA time zone database. See the list of possible values.	1.2
ip_asnum	string	The autonomous system number associated with the IP address.	1.2
ip_userType	enum	The user type associated with the IP address. This will be one of the following values. business cafe cellular college contentDeliveryNetwork government hosting library military residential router school searchEngineSpider traveler	1.2
ip_netSpeedCell	enum	The network speed associated with the IP address. This can be one of the following values: Dialup Cable/DSL Corporate Cellular	1.2
ip_domain	string	The second level domain associated with the IP address. This will be something like "example.com" or "example.co.uk", not "foo.example.com".	1.2
ip_isp	string	The name of the ISP associated with the IP address.	1.0
ip_org	string	The name of the organization associated with the IP address.	1.0
ip_cityConf	decimal	A value from 0-100 representing our confidence that the city is correct.	1.2
ip_regionConf	decimal	A value from 0-100 representing our confidence that the region is correct.	1.2
ip_postalConf	decimal	A value from 0-100 representing our confidence that the postal code is correct.	1.2
ip_countryConf	decimal	A value from 0-100 representing our confidence that the country is correct.	1.2
Proxy Detection These fields provide information about whether or not the user's IP address is a proxy, and if so, what type of proxy.
anonymousProxy	enum	This field can be either Yes or No. It indicates whether the user's IP address is an anonymous proxy. An anonymous proxy indicates a high risk of fraud.	1.0
proxyScore	decimal	A score from 0.00-4.00 indicating the likelihood that the user's IP address is an open proxy.	1.0
isTransProxy	enum	This field can be either Yes or No. It indicates whether the user's IP address is in our database of known transparent proxy servers. This is only returned if the forwardedIP field was set in the input.	1.0
ip_corporateProxy	enum	This field can be either Yes or No. It indicates whether the user's IP address is a known corporate proxy.	1.2
Emails and Login Checks These fields provide information about the email and login info that was provided in the input.
freeMail	enum	This field can be either Yes or No. It indicates whether the user's email address is from a free email provider. Note that this will be set to "No" if no domain is passed in the input.	1.0
carderEmail	enum	This field can be either Yes or No. It indicates whether the user's email address is in a database of known high risk emails.	1.0
highRiskUsername		This field does not return useful data. It will be removed in a future release.	1.0
highRiskPassword		This field does not return useful data. It will be removed in a future release.	1.0
Bank Checks These fields provide information about the user's credit card and its issuing bank.
binMatch	enum	This field can be either Yes, No, NotFound, or NA It indicates whether the credit's card bank is in the same country as the user's billing address. The NotFound response means that we could not find a match for the provided bin input field. The NA response means that you did not provide a bin in the input.	1.1
binCountry	string (2)	The two letter ISO 3166 country code for the bank.	1.1
binNameMatch	enum	This field can be either Yes, No, NotFound, or NA It indicates whether the credit's card bank name matches the binName input field. The NotFound response means that we could not find a match for the provided bin input field. The NA response means that you did not provide a binName in the input.	1.1
binName	string	The name of the bank which issued the credit card. This is available for approximately 96% of all BIN numbers. This field is only returned for premium service level queries.	1.1
binPhoneMatch	enum	This field can be either Yes, No, NotFound, or NA It indicates whether the credit's card bank name matches the binPhone input field. The NotFound response means that we could not find a match for the provided bin input field. The NA response means that you did not provide a binPhone in the input.	1.1
binPhone	string	The phone number of the bank which issued the credit card. This is available for approximately 75% of all BIN numbers. In some cases the phone number we return may be out of date. This field is only returned for premium service level queries.	1.1
prepaid	enum	This field can be either Yes or No. This indicates whether the card is a prepaid or gift card. If no bin input was provided, this field will be left blank.	1.3
Address and Phone Number Checks These fields provide information the user's phone and address.
custPhoneInBillingLoc	enum	This field can be either Yes, No, or NotFound. This indicates whether the customer's phone number is in the billing address's postal code. The No response means that phone number may be in a different area, or it is not listed in our database. The NotFound response indicates that the phone number prefix is not in our database. Currently we only return information about US phone numbers. For all other countries, this field will be left blank.	1.0
shipFoward	enum	This field can be either Yes, No, or NA. This indicates whether the customer's shipping address is in a database of known high risk shipping addresses. The NA response indicates that we could not parse the shipping address.	1.0
cityPostalMatch	enum	This field can be either Yes or No. This indicates whether the customer's billing city and state match their postal code. This is currently only available for US addresses. For addresses outside the US, this field is empty.	1.0
shipCityPostalMatch	enum	This field can be either Yes or No. This indicates whether the customer's shipping city and state match their postal code. This is currently only available for US addresses. For addresses outside the US, this field is empty.	1.0
Account Information Fields These fields provide information about your MaxMind account.
queriesRemaining	integer	This is the number of minFraud queries remaining in your account.	1.0
maxmindID	string (8)	This is a unique eight character string identifying this minFraud request. Please use this ID in bug reports or support requests to MaxMind so that we can easily identify a particular request.	1.0
minfraud_version	string	This returns the API version that was used for this request.	1.0
service_level	enum	This returns the service level that was used for this request. This can be either standard or premium.	1.0
Error Reporting
err	enum	If there was an error or warning with this request, this field contains an error code string. The possible error codes are: INVALID_LICENSE_KEY IP_REQUIRED IP_NOT_FOUND - this error will be returned if the IP address is not valid, if it is not public, or if it is not in our GeoIP database. LICENSE_REQUIRED COUNTRY_REQUIRED MAX_REQUESTS_REACHED - this is returned when a trial account runs out of free queries. The possible warning codes are: COUNTRY_NOT_FOUND CITY_NOT_FOUND CITY_REQUIRED POSTAL_CODE_REQUIRED POSTAL_CODE_NOT_FOUND	1.0

SOAP API

In addition to the HTTP API, MaxMind also offers a SOAP API for minFraud. Download one of the WSDL files below. We recommend using the latest version if you can.

WSDL version 14
WSDL version 13
WSDL version 11
WSDL version 10
WSDL version 9
WSDL version 8
WSDL version 7
WSDL version 6
WSDL version 5
WSDL version 4
WSDL version 3
WSDL version 2

MaxMind main site
Terms of Use
Support

minFraud Web Service API

Table of Contents

Client APIs

HTTP API

Input

Required Fields

Shipping Address

User Data

BIN-related

Transaction Linking

Transaction Information

Credit Card Check

Miscellaneous

Output

Risk Score

GeoIP Location Checks

Proxy Detection

Emails and Login Checks

Bank Checks

Address and Phone Number Checks

Account Information Fields

Error Reporting

SOAP API