> **Note** > We have made a number of data changes to the minFraud Legacy Standard and Premium, and GeoIP Legacy City and Insights (formerly Omni) web services. Please see our [blog post](https://blog.maxmind.com/data-changes-to-geoip-legacy-and-minfraud-legacy-web-services-in-may-2022/) for more information, and how to prepare. > **New minFraud APIs are available:** Please see [What’s New in minFraud Score, minFraud Insights, and minFraud Factors](/minfraud/whats-new-in-minfraud-score-and-minfraud-insights) and our [minFraud Insights, minFraud Score, and minFraud Factors API documentation](/minfraud). To learn more about the minFraud Insights, minFraud Score, and minFraud Factors services and to purchase credits, please [visit the minFraud Overview page](https://www.maxmind.com/en/solutions/fraud-prevention/overview). The minFraud web service is available using a simple URI-based API. To use this service, you must have a valid [MaxMind license key](https://www.maxmind.com/en/accounts/current/license-key). ## Report Transactions If you are using our minFraud transaction fraud detection service, we also encourage you to use our [report transaction service](/minfraud/report-a-transaction/). By reporting false positives and instances of fraud to us, you can help us refine our algorithms, so we can reduce false positives and catch more fraud. ## Device Tracking Add-On You may optionally include the [Device Tracking Add-On](/minfraud/track-devices/) to help us identify the device your customer is using to determine whether it has been used in previous fraudulent transactions. The device information is factored into the scores returned through the minFraud service. ## 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/minfraud/v1.0/legacy`. You may be using the original URI, `https://minfraud.maxmind.com/app/ccv2r`. The `minfraud.maxmind.com` hostname automatically picks the data center geographically closest to you. ### Security The API is only available via HTTPS. If you attempt to access this service via HTTP, you will receive a `403 Forbidden` HTTP response. We require TLS 1.2 or greater for all requests to our servers to keep your data secure. ### HTTP status codes In addition to the error code returned in the response body, this service uses the HTTP status code to indicate certain error conditions. This lets you act on these conditions from the HTTP status code, for example in your monitoring or an internal proxy, without parsing the response body. | HTTP status | Condition | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `200 OK` | The request was processed. This includes successful lookups and lookups that return a warning code in the response body. | | `400 Bad Request` | The request was malformed. | | `401 Unauthorized` | The license key is missing or invalid (`LICENSE_REQUIRED` or `INVALID_LICENSE_KEY`). | | `402 Payment Required` | Your account is out of queries (`MAX_REQUESTS_REACHED`). | | `403 Forbidden` | Your account does not have permission to use this service (`PERMISSION_REQUIRED`). | | `5xx` | A server error occurred. | Where applicable, the response body returns an `err` value with the relevant error code. Warning conditions, including `IP_NOT_FOUND`, return a `200 OK` status. ### 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. String fields are limited to no more than 255 Unicode characters unless a shorter length is specified. Of course, many fields also have additional constraints that limit the length. For example, the `ip_address` field cannot be longer than the longest valid representation of an IPv6 address.
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”.
license_key string Your MaxMind license key.
Billing Address You should always pass these fields if possible.
city string (255) The billing city for the customer.
region string (255) The billing region/state for the customer.
postal string (255) The billing postal (zip) code for the customer.
country string (255) The billing country for the customer. This can be passed as the full country name or as an ISO 3166 code.
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 (255) The shipping street address.
shipCity string (255) The shipping address city.
shipRegion string (255) The shipping address region/state.
shipPostal string (255) The shipping address postal (zip) code.
shipCountry string (255) 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 (255) The domain for the user’s email address. This field should not be hashed.
custPhone string (255) The customer’s phone number. Most formats are acceptable. We strip out all non-numeric characters from the input.
emailMD5 string (32) The customer’s email address. This field must be a valid email address or the MD5 of the lowercased email address. Important: if using the MD5 hash, please be sure to normalize it before calculating its MD5 hash.
usernameMD5 string (32) An MD5 hash of the user’s username in ASCII encoding.
BIN-related These fields are used to verify that the customer is in possession of the credit card.
bin string (255) The credit card BIN number. This is the first 6 or 8 digits of the credit card number. It identifies the issuing bank.
binName string (255) The name of the bank which issued the credit card as provided by the end-user who initiated the event. 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 (255) The customer service phone number listed on the back of the credit card as provided by the end-user who initiated the event. 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.
user_agent string (255) The User-Agent HTTP header.
accept_language string (255) The Accept-Language HTTP header.
Transaction Information These fields provide additional information about the transaction.
txnID string (255) 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 (17, 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 (255) Your internal ID for the shop, affiliate, or merchant this order is coming from. Required for minFraud users who are resellers, payment providers, gateways and affiliate networks.
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 supports the standard AVS codes.
cvv_result enum The card verification value (CVV) code as provided by the payment processor. This should be a single letter. 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.
### Output The minFraud service returns its output as a set of fields separated by semicolons (;). Each field consists of a name and value separated by an equals sign (=). The field values are not escaped, but will never contain a semicolon or equals sign. All strings are returned in the [ISO-8859-1 encoding](https://en.wikipedia.org/wiki/ISO/IEC_8859-1). 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 specifies the earliest API version in which a field is available. You can explicitly [ask for responses in older API formats](/minfraud/minfraud-legacy). 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, is not supported, and is no longer present in API version 1.3. 1.0
explanation string This field has been deprecated, is not supported, and is no longer present in API version 1.3. This is a brief explanation of the score (not the riskScore). 1.1
GeoIP Location Checks These fields are based on the correspondence 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. If no country input was provided, this field will be left blank. 1.0
highRiskCountry enum This field has been deprecated. 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 as defined by GeoNames associated with the IP address. 1.0
ip_region string The ISO-3166-2 code for the state/region associated with the IP address. We previously returned a FIPS 10-4 code for all countries other than the United States and Canada. See our blog post for more information. 1.0
ip_regionName string The region name as defined by GeoNames 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 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 first 2-4 characters (outward code) for postal codes in the United Kingdom. 1.2
ip_metroCode integer Deprecated. This is a no-longer-maintained code for targeting advertisements in Google. 1.2
ip_areaCode string Deprecated. This field is empty. See our blog post for more information. 1.2
countryCode string A 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 as defined by GeoNames 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
  • AN – Antarctica
  • AS – Asia
  • EU – Europe
  • NA – North America
  • OC – Oceania
  • SA – South America
 1.2
ip_latitude decimal The approximate latitude of the location associated with the IP address. This value is not precise and should not be used to identify a particular address or household. The latitude and longitude are near the center of the most granular location value returned: postal code, city, region, or country. 1.0
ip_longitude decimal The approximate longitude of the location associated with the IP address. This value is not precise and should not be used to identify a particular address or household. 1.0
ip_timeZone string The time zone associated with the IP address. Time zone names are taken from the IANA time zone database. 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 connection type 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 high risk.
proxyScore Likelihood of fraud
0.5 15%
1.0 30%
2.0 60%
3.0+ 90%
Note: Anonymous proxies will generally return a proxyScore of 0. 		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 has been deprecated. It will be removed in a future release. 1.0
highRiskPassword This field has been deprecated. 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 country of the billing address matches the country of the majority of customers using that BIN. In cases where the location of customers is highly mixed, the match is to the country of the bank issuing the card. 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.0
binCountry string (2) The two letter ISO 3166-1 alpha-2 country code associated with the location of the majority of customers using this credit card as determined by their billing address. In cases where the location of customers is highly mixed, this defaults to the country of the bank issuing the card. This field is returned for premium service level queries. For standard service level queries the field is only returned if the binMatch is Yes. 1.0
binNameMatch enum This field can be either Yes, No, NotFound, or NA. It indicates whether the credit card’s 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 card’s bank phone number 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.0
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.0
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. This field is only returned for premium service level queries. 1.3
Address and Phone Number Checks These fields provide information about 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
shipForward 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. 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. 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.3
service_level enum This returns the service level that was used for this request. This can be either standard or premium. 1.3
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
  • MAX_REQUESTS_REACHED – This is returned when your account is out of queries.
  • LICENSE_REQUIRED – This is returned if you do not provide a license key at all.
  • PERMISSION_REQUIRED – This is returned if you do not have permission to use the service. Please contact our support team for more information.
The possible warning codes are:
  • COUNTRY_NOT_FOUND
  • CITY_NOT_FOUND
  • CITY_REQUIRED
  • INVALID_EMAIL_MD5
  • IP_NOT_FOUND – This warning will be returned if the IP address is not valid, if it is not public, or if it is not in our GeoIP database.
  • POSTAL_CODE_REQUIRED
  • POSTAL_CODE_NOT_FOUND
 1.0
## Testing minFraud Legacy with the MaxMind Sandbox MaxMind maintains a Sandbox environment so that you can do basic integration tests with the web services. In order to set up a Sandbox account you must already have a paid account, and you must be an account administrator. [Learn how to set up a Sandbox account on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/set-up-a-maxmind-sandbox-account) Once you have your Sandbox account set up and activated, follow the steps below. ### Select the proper Legacy version for testing > Please note that if you would like to test the current version of the minFraud service, you should follow the [instructions for testing the current minFraud service on the Sandbox](/minfraud/sandbox-environment). You can control which version of the Legacy minFraud service your Sandbox account uses. Once an account administrator has set up your Sandbox environment and granted you access, you can login to your Sandbox account and click on “minFraud Version” in the minFraud section of the left-hand navigation menu [[direct link](https://sandbox.maxmind.com/en/accounts/current/minfraud/legacy-version), Sandbox account login required]. Select the version of minFraud you would like to test, and click the blue Submit button. The latest version of minFraud will be selected by default when you initialize your Sandbox environment. ### Generate a License Key for the Sandbox In order to test the web services in the Sandbox environment, you will need to generate a license key from your Sandbox account. [Learn how to generate a license key on our Knowledge Base.](https://support.maxmind.com/knowledge-base/articles/generate-a-maxmind-license-key) The process is the same for your Sandbox account, but you must login to your Sandbox account [[direct link](https://sandbox.maxmind.com/en/accounts/current/license-key), Sandbox account login required] rather than your regular MaxMind account. ### Point your integration to the Sandbox service endpoints Use the service endpoint for the Sandbox version of the minFraud Legacy service: `https://sandbox.maxmind.com/minfraud/v1.0/legacy` If you are using the original URI, you can also test using that URI on the Sandbox: `https://sandbox.maxmind.com/app/ccv2r` Remember to use the license key generated by your Sandbox account to authenticate your requests. ### Test data for the Sandbox minFraud Legacy service You may only submit approved test data to the Sandbox version of the minFraud services. At this time, the only approved test transaction data are the three IP addresses listed below. You can submit transactions to Sandbox minFraud Legacy services with any of the following IP addresses as the required `i` (IP address input). [Learn more about Legacy inputs above.](#input) You should receive a minFraud response with risk scores and risk data. The `proxyScore` output will contain a response within the range defined below: | Test IP Address Input | Test proxyScore Output Range | | --------------------- | ---------------------------- | | `128.101.101.101` | 2 - 4 | | `74.209.24.1` | 0.5 - 1.99 | | `65.116.3.80` | 0 - 0.49 | Here is an example request that should return a valid minFraud response without any warnings or errors, and with a proxyScore between 2 and 4: - `https://sandbox.maxmind.com/minfraud/v1.0/legacy?i=128.101.101.101&license_key=&country=US` You should not submit real transaction data to the Sandbox version of the minFraud Legacy services, but you can submit transactions with dummy data. The Sandbox environment imposes volume limits on API requests to prevent abuse. The Sandbox should not be used to test the capacity of the production web service in high volume situations. If you are running into the request limit and need help, please [reach out to our support team for assistance](https://support.maxmind.com/knowledge-base). ### Learn more about the MaxMind Sandbox You can [learn more about the MaxMind Sandbox on our Knowledge Base](https://support.maxmind.com/knowledge-base/account-and-purchasing#sandbox-environment).