minFraud Score, minFraud Insights, and minFraud Factors API

If you are a minFraud Legacy customer, please see our “What’s New in minFraud Score, minFraud Insights, and minFraud Factors” document for a summary of the changes.

Release Notes

Changes to the minFraud web services are documented in our release notes.

Client APIS

MaxMind APIs

If you are using one of the languages listed in the table below, we strongly encourage you to use the officially supported library. There will be no need to interface with the REST API directly.

Language or Framework Package Repository Documentation Version Control
.NET (C#) NuGet GitHub Pages GitHub
Java Maven Central GitHub Pages GitHub
Perl metacpan metacpan GitHub
PHP Packagist GitHub Pages GitHub
Python PyPI Read the Docs GitHub

Third-Party APIs

Warning! MaxMind does not offer support for these APIs and has not reviewed the code. Use at your own risk.
Language or Framework API Name Package Repository Documentation Version Control
Ruby minfraud RubyGems.org RubyDoc.info GitHub

Chargeback Reporting

If you are using our minFraud transaction fraud detection service, we also encourage you to use our chargeback reporting service. By reporting instances of fraud to us, you can help us tune our algorithms further, reducing fraud even more in the future.

Device Tracking Add-on

You may optionally include some JavaScript on your site that helps 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.

Per-Service URIs

The URI for each service is as specified below. All API calls should be made with HTTP POST using the request format specified below.

Please note that the free minFraud service trial provides access to the minFraud Score and minFraud Insights services only.

To learn more about gaining access to the minFraud Factors service, please complete the minFraud Factors information request form.

Service URI Content-Type
Score https://minfraud.maxmind.com/minfraud/v2.0/score application/vnd.maxmind.com-minfraud-score+json; charset=UTF-8; version=2.0
Insights https://minfraud.maxmind.com/minfraud/v2.0/insights application/vnd.maxmind.com-minfraud-insights+json; charset=UTF-8; version=2.0
Factors https://minfraud.maxmind.com/minfraud/v2.0/factors application/vnd.maxmind.com-minfraud-factors+json; charset=UTF-8; version=2.0

Request Headers

The Accept header for a request is entirely optional. If you do include one, you must accept one of the following:

  • application/json
  • application/vnd.maxmind.com-minfraud-score+json
  • application/vnd.maxmind.com-minfraud-score+json; charset=UTF-8; version=2.0

Substitute the appropriate service’s type for “score”. A request for any other MIME type will result in a 415 Unsupported Media Type error.

If you set the Accept-Charset header in your client code, you must accept the UTF-8 character set. If you don’t you will receive a 406 Not Acceptable response, because this data is only available in UTF-8.

Authorization

The HTTP Authorization header is required for authorization. The username is your MaxMind user ID. The password is your MaxMind license key. You must request a demo or subscribe to one of our web services in order to receive a user ID and license key.

We use basic HTTP authentication. The APIs which require authentication are only available via HTTPS. The credentials are never transmitted unencrypted. If you attempt to access this service via HTTP, you will receive a 403 Forbidden HTTP response.

Request Body

Currently minFraud Score, minFraud Insights, and minFraud Factors use the same request document format. The request consists of a JSON object with one or more of the fields shown below. Each key in the top-level object maps to an object or array as described below. New fields that apply to one or both may be added in the future.

The only input that is required is the ip_address field in the device object. In the future, this requirement may be dropped.

String fields are limited to no more than 255 Unicode characters unless a shorter length is specified; the null character is forbidden. 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.

The entire request body is limited to 20,000 bytes. Requests larger than this size will be rejected.

Example Request

Top-Level Request Fields (/)

Device (/device)

This object contains information about the device used in the transaction. (Required)

Key Value Type Description
ip_address string The IP address associated with the device used by the customer in the transaction. The IP address must be in IPv4 or IPv6 presentation format, i.e., dotted-quad notation or the IPv6 hexadecimal-colon notation. (Required)
user_agent string (255) The HTTP “User-Agent” header of the browser used in the transaction.
accept_language string (255) The HTTP “Accept-Language” header of the device used in the transaction.

Event (/event)

This object contains general information related to the event being scored.

Key Value Type Description
transaction_id string (255) Your internal ID for the transaction. 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.
shop_id 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.
time string The date and time the event occurred. The string must be in the RFC 3339 date-time format, e.g., “2012-04-12T23:20:50.52Z”. If this field is not in the request, the current time will be used.
type enum

The type of event being scored. The valid types are:

  • account_creation
  • account_login
  • email_change
  • password_reset
  • purchase
  • recurring_purchase
  • referral
  • survey

Account (/account)

This object contains account information for the end-user on the site where the event took place.

Key Value Type Description
user_id string (255) A unique user ID associated with the end-user in your system. If your system allows the login name for the account to be changed, this should not be the login name for the account, but rather should be an internal ID that does not change. This is not your MaxMind user ID.
username_md5 string (32) An MD5 hash as a hexadecimal string of the username or login name associated with the account.

Email (/email)

Key Value Type Description
address string (255) This field must be either be a valid email address or an MD5 of the email used in the transaction.
domain string (255) The domain of the email address used in the transaction.

Billing (/billing)

Key Value Type Description
first_name string (255) The first name of the end user as provided in their billing information.
last_name string (255) The last name of the end user as provided in their billing information.
company string (255) The company of the end user as provided in their billing information.
address string (255) The first line of the user’s billing address.
address_2 string (255) The second line of the user’s billing address.
city string (255) The city of the user’s billing address.
region string (4) The ISO 3166-2 subdivision code for the user’s billing address.
country string (2) The two character ISO 3166-1 alpha-2 country code of the user’s billing address.
postal string (255) The postal code of the user’s billing address.
phone_number string (255) The phone number without the country code for the user’s billing address.
phone_country_code string (4) The country code for phone number associated with the user’s billing address.

Shipping (/shipping)

Key Value Type Description
first_name string (255) The first name of the end user as provided in their shipping information.
last_name string (255) The last name of the end user as provided in their shipping information.
company string (255) The company of the end user as provided in their shipping information.
address string (255) The first line of the user’s shipping address.
address_2 string (255) The second line of the user’s shipping address.
city string (255) The city of the user’s shipping address.
region string (4) The ISO 3166-2 subdivision code for the user’s shipping address.
country string (2) The two character ISO 3166-1 alpha-2 country code of the user’s shipping address.
postal string (255) The postal code of the user’s shipping address.
phone_number string (255) The phone number without the country code for the user’s shipping address.
phone_country_code string (4) The country code for phone number associated with the user’s shipping address.
delivery_speed enum

The shipping delivery speed for the order. The valid values are:

  • same_day
  • overnight
  • expedited
  • standard

Payment (/payment)

Key Value Type Description
processor enum

The payment processor used for the transaction. The valid values are:

  • adyen
  • altapay
  • amazon_payments
  • authorizenet
  • balanced
  • beanstream
  • bluepay
  • braintree
  • ccnow
  • chase_paymentech
  • cielo
  • collector
  • compropago
  • concept_payments
  • conekta
  • cuentadigital
  • dalpay
  • dibs
  • digital_river
  • ecomm365
  • elavon
  • epay
  • eprocessing_network
  • eway
  • first_data
  • global_payments
  • ingenico
  • internetsecure
  • intuit_quickbooks_payments
  • iugu
  • mastercard_payment_gateway
  • mercadopago
  • merchant_esolutions
  • mirjeh
  • mollie
  • moneris_solutions
  • nmi
  • openpaymx
  • optimal_payments
  • orangepay
  • other
  • pacnet_services
  • payfast
  • paygate
  • payone
  • paypal
  • payplus
  • paystation
  • paytrace
  • paytrail
  • payture
  • payu
  • payulatam
  • pinpayments
  • princeton_payment_solutions
  • psigate
  • qiwi
  • quickpay
  • raberil
  • rede
  • redpagos
  • rewardspay
  • sagepay
  • simplify_commerce
  • skrill
  • smartcoin
  • sps_decidir
  • stripe
  • telerecargas
  • towah
  • usa_epay
  • verepay
  • vindicia
  • virtual_card_services
  • vme
  • worldpay
If your payment processor is missing from this list, please contact support@maxmind.com.
was_authorized boolean The authorization outcome from the payment processor. If the transaction has not yet been approved or denied, do not include this field.
decline_code string (255) The decline code as provided by your payment processor. If the transaction was not declined, do not include this field.

Credit Card (/credit_card)

Key Value Type Description
issuer_id_number string (6) The issuer ID number for the credit card. This is the first 6 digits of the credit card number. It identifies the issuing bank.
last_4_digits string (4) The last four digits of the credit card number.
token string (255) A token uniquely identifying the card. The token should consist of non-space printable ASCII characters. If the token is all digits, it must be more than 19 characters long. The token must not be a primary account number (PAN) or a simple transformation of it. If you have a valid token that looks like a PAN but is not one, you may prefix that token with a fixed string, e.g., token-.
bank_name string (255) The name of the issuing bank as provided by the end user.
bank_phone_country_code string (4) The phone country code for the issuing bank as provided by the end user.
bank_phone_number string (255) The phone number, without the country code, for the issuing bank as provided by the end user.
avs_result character (1) The address verification system (AVS) check result, as returned to you by the credit card processor. The minFraud service supports the standard AVS codes.
cvv_result character (1) The card verification value (CVV) code as provided by the payment processor.

Order (/order)

Key Value Type Description
amount decimal The total order amount for the transaction.
currency string (3) The ISO 4217 currency code for the currency used in the transaction.
discount_code string (255) The discount code applied to the transaction. If multiple discount codes were used, please separate them with a comma.
affiliate_id string (255) The ID of the affiliate where the order is coming from.
subaffiliate_id string (255) The ID of the sub-affiliate where the order is coming from.
referrer_uri string (1024) The URI of the referring site for this order.
is_gift boolean Whether order was marked as a gift by the purchaser.
has_gift_message boolean Whether the purchaser included a gift message.

Shopping Cart (/shopping_cart)

This is an array of shopping cart item objects. A shopping cart should consist of an array of one or more item objects.

Shopping Cart Item
Key Value Type Description
category string (255) The category of the item.
item_id string (255) Your internal ID for the item.
quantity integer The quantity of the item in the shopping cart.
price decimal The per-unit price of this item in the shopping cart. This should use the same currency as the order currency.

Response Headers

The Content-Type header for a successful response varies based on the service as outlined above.

Errors may be returned with the Content-Type set to application/vnd.maxmind.com-error+json; charset=UTF-8; version=2.0. If this is the case, then the body of the response contains a JSON document with two keys, code and error. See the Errors section for more details.

The response will always include a Content-Length header as well.

Response Body

All services return data as a JSON document. The document that is returned always consists of an object (aka map or hash).

Keys with undefined or empty values will not be included in the returned document.

The data returned in the document will be in UTF-8 encoding.

Note that a given key and value may be omitted from the response entirely if there is no relevant information to include. For example, if you do not pass any information about the credit card in your request, then the response will not contain a credit_card key or value.

Top-Level Fields (/)

Included in …
Key Value Type Description Score? Insights? Factors?
id string (UUID) This is the minFraud ID, a UUID that identifies the minFraud response. Use this ID to search your minFraud logs or when making support requests to MaxMind.
risk_score decimal This field contains the risk score, from 0.01 to 99. 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. Likewise we never return a risk score of 100.
credits_remaining integer Deprecated. This field will be removed before the final release. The approximate number of service credits remaining on your account.
funds_remaining decimal The approximate US dollar value of the funds remaining on your MaxMind account. Although currently not returned, this field will be available before the final release.
queries_remaining integer The approximate number of queries remaining for the service before your account runs out of funds.
warnings array This array contains warning objects detailing issues with the request that was sent such as invalid or unknown inputs. It is highly recommended that you check this array for issues when integrating the web service.

IP Address (/ip_address)

For minFraud Score, this object only contains the risk for the IP address. For minFraud Insights and Factors, the object is the GeoIP2 Insights response body with three additions: (1) risk has been added directly to the ip_address object; (2) is_high_risk has been added to the country sub-object; and (3) local_time has been added to the location sub-object. See below for descriptions.

Included in …
Key Value Type Description Score? Insights? Factors?
risk decimal This field contains the risk associated with the IP address. The value ranges from 0.01 to 99. A higher score indicates a higher risk.

Country (/ip_address/country)

Included in …
Key Value Type Description Score? Insights? Factors?
is_high_risk boolean This value is true if the IP country is high risk.

Location (/ip_address/location)

Key Value Type Description Score? Insights? Factors?
local_time string (255) The date and time of the transaction in the time zone associated with the IP address. The value is formatted according to RFC 3339. For instance, the local time in Boston might be returned as 2015-04-27T19:17:24-04:00.

Credit Card (/credit_card)

This object contains minFraud information related to the credit card. If an issuer ID number (IIN) was not provided in the request, this object will not be present in the response.

Included in …
Key Value Type Description Score? Insights? Factors?
issuer object This field contains a JSON object with information relating to the credit card issuer.
brand string (255) The card brand, such as “Visa”, “Discover”, “American Express”, etc.
country 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.
is_issued_in_billing_address_country boolean This field is true if the country of the billing address matches the country of the majority of customers using that IIN. In cases where the location of customers is highly mixed, the match is to the country of the bank issuing the card.
is_prepaid boolean This field is true if the card is a prepaid card.
type enum

The card’s type. The valid values are:

  • charge – See Wikipedia for an explanation of the difference between charge and credit cards.
  • credit
  • debit

Credit Card Issuer (/credit_card/issuer)

This is a sub-object of credit_card that contains information related to the issuer of the card.

Included in …
Key Value Type Description Score? Insights? Factors?
name string (255) The name of the bank which issued the credit card.
matches_provided_name boolean This field is true if the name matches the name provided in the request for the card issuer. It is false if the name does not match. The field is not included if either no name or issuer ID number (IIN) was provided in the request or if MaxMind does not have a name associated with the IIN.
phone_number string (255) The phone number of the bank which issued the credit card. In some cases the phone number we return may be out of date.
matches_provided_phone_number boolean This field is true if the phone number matches the number provided in the request for the card issuer. It is false if the number does not match. The field is not included if either no phone number or issuer ID number (IIN) was provided in the request or if MaxMind does not have a phone number associated with the IIN.

Device

This object contains information about the device that MaxMind believes is associated with the IP address passed in the request.

Included in …
Key Value Type Description Score? Insights? Factors?
confidence decimal A number from 0.01 to 99 representing the confidence that the /device/id refers to a unique device as opposed to a cluster of similar devices. A confidence of 0.01 indicates very low confidence that the device is unique, whereas 99 indicates very high confidence.
id UUID A UUID that MaxMind uses for the device associated with this IP address. Note that many devices cannot be uniquely identified because they are too common (for example, all iPhones of a given model and OS release). In these cases, the minFraud service will simply not return a UUID for that device. This is only available if you are using the Device Tracking Add-on.
last_seen string (255) The date and time of the last sighting of the device. The value is formatted according to RFC 3339.

Email

This object contains information about the email address passed in the request.

Included in …
Key Value Type Description Score? Insights? Factors?
is_free boolean This field is true if MaxMind believes that this email is hosted by a free email provider such as Gmail or Yahoo! Mail.
is_high_risk boolean This field is true if MaxMind believes that this email is likely to be used for fraud. Note that this is also factored into the overall risk_score in the response as well.

Shipping Address (/shipping_address)

This object contains minFraud response data associated with the shipping address. If the shipping address was not provided in the request or could not be parsed, this object will not be present in the response.

Included in …
Key Value Type Description Score? Insights? Factors?
is_high_risk boolean This field is true if the shipping address is an address associated with fraudulent transactions. The field is false when the address is not associated with increased risk.
is_postal_in_city boolean This field is true if the postal code provided with the address is in the city for the address. The field is false when the postal code is not in the city.
latitude decimal The approximate latitude associated with the address.
longitude decimal The approximate longitude associated with the address.
distance_to_ip_location integer The distance in kilometers from the address to the IP location.
distance_to_billing_address integer The distance in kilometers from the shipping address to billing address.
is_in_ip_country boolean This field is true if the shipping address is in the IP country. The field is false when the address is not in the IP country. If the IP address could not be geolocated, then the field will not be included in the response.

Billing Address (/billing_address)

This object contains minFraud response data associated with the billing address. If the billing address was not provided in the request or could not be parsed, this object will not be present in the response.

Included in …
Key Value Type Description Score? Insights? Factors?
is_postal_in_city boolean This field is true if the postal code provided with the address is in the city for the address. The field is false when the postal code is not in the city.
latitude decimal The approximate latitude associated with the address.
longitude decimal The approximate longitude associated with the address.
distance_to_ip_location integer The distance in kilometers from the address to the IP location.
is_in_ip_country boolean This field is true if the address is in the IP country. The field is false when the address is not in the IP country. If the IP address could not be geolocated, the field will not be included in the response.

Disposition (/disposition)

This object contains information about how a request was handled by the custom rules you have defined. If your account does not have any custom rules defined, then this object will not be present in the response.

Included in …
Key Value Type Description Score? Insights? Factors?
action enum

This describes how the request was handled. The valid values are:

  • accept – this is the default value that is used if none your custom rules match the request
  • reject
  • manual_review
reason enum

This describes why the action was set to a particular value. The valid values are:

  • default – no custom rules matched the request
  • custom_rule – a custom rule was applied and set the action

Subscores (/subscores)

This object contains subscores for many of the individual components that are used in calculating the risk_score.

This object is only included with minFraud Factors.
Included in …
Key Value Type Description Score? Insights? Factors?
avs_result decimal The risk associated with the AVS result. If present, this is a value in the range 0.01 to 99.
billing_address decimal The risk associated with the billing address. If present, this is a value in the range 0.01 to 99.
billing_address_distance_to_ip_location decimal The risk associated with the distance between the billing address and the location for the given IP address. If present, this is a value in the range 0.01 to 99.
browser decimal The risk associated with the browser attributes such as the User-Agent and Accept-Language. If present, this is a value in the range 0.01 to 99.
chargeback decimal Individualized risk of chargeback for the given IP address on your account and shop ID.This is only available to users sending chargeback data to MaxMind. If present, this is a value in the range 0.01 to 99.
country decimal The risk associated with the country the transaction originated from. If present, this is a value in the range 0.01 to 99.
country_mismatch decimal The risk associated with the combination of IP country, card issuer country, billing country, and shipping country. If present, this is a value in the range 0.01 to 99.
cvv_result decimal The risk associated with the CVV result. If present, this is a value in the range 0.01 to 99.
email_address decimal The risk associated with the particular email address. If present, this is a value in the range 0.01 to 99.
email_domain decimal The general risk associated with the email domain. If present, this is a value in the range 0.01 to 99.
email_tenure decimal The risk associated with the issuer ID number on the email domain. If present, this is a value in the range 0.01 to 99.
ip_tenure decimal The risk associated with the issuer ID number on the IP address. If present, this is a value in the range 0.01 to 99.
issuer_id_number decimal The risk associated with the particular issuer ID number (IIN) given the billing location and the history of usage of the IIN on your account and shop ID. If present, this is a value in the range 0.01 to 99.
order_amount decimal The risk associated with the particular order amount for your account and shop ID. If present, this is a value in the range 0.01 to 99.
phone_number decimal The risk associated with the particular phone number. If present, this is a value in the range 0.01 to 99.
shipping_address_distance_to_ip_location decimal The risk associated with the distance between the shipping address and the location for the given IP address. If present, this is a value in the range 0.01 to 99.
time_of_day decimal The risk associated with the local time of day of the transaction in the IP address location. If present, this is a value in the range 0.01 to 99.

Warning

Included in …
Key Value Type Description Score? Insights? Factors?
code string (255)

This value is a machine-readable code identifying the warning. Although more codes may be added in the future, the current codes are:

  • BILLING_CITY_NOT_FOUND – the billing city could not be found in our database.
  • BILLING_COUNTRY_NOT_FOUND – the billing country could not be found in our database.
  • BILLING_POSTAL_NOT_FOUND – the billing postal could not be found in our database.
  • INPUT_INVALID – the value associated with the key does not meet the required constraints, e.g., “United States” in a field that requires a two-letter country code.
  • INPUT_UNKNOWN – an unknown key was encountered in the request body.
  • IP_ADDRESS_NOT_FOUND – the IP address could not be geolocated.
  • SHIPPING_CITY_NOT_FOUND – the shipping city could not be found in our database.
  • SHIPPING_COUNTRY_NOT_FOUND – the shipping country could not be found in our database.
  • SHIPPING_POSTAL_NOT_FOUND – the shipping postal could not be found in our database.
warning string (255) This field provides a human-readable explanation of the warning. The description may change at any time and should not be matched against.
input_pointer JSON Pointer string A JSON Pointer to the input field that the warning is associated with. For instance, if the warning was about the billing city, this would be /billing/city. If it was for the price in the second shopping cart item, it would be /shopping_cart/1/price

Response Body Examples

Errors

When the server returns an error (4xx or 5xx), the response may include a JSON document in the body. This document is a single object with the keys code and error. The code field is a static error code for machine use. The value of any given code will never change, though codes can be added or removed. The error field is a human-readable description of the error and may change at any time.

Not all errors include a JSON body. An error in content negotiation will not include a body, nor will many 5xx errors, which typically happen outside of our web service request handling code. You should check the Content-Type type of an error response before attempting to decode the body as JSON.

In addition to the errors documented below, client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.

Code HTTP Status Description
IP_ADDRESS_INVALID 400 Bad Request

You have not supplied a valid IPv4 or IPv6 address.

IP_ADDRESS_REQUIRED 400 Bad Request

You have not supplied an IP address, which is a required field.

IP_ADDRESS_RESERVED 400 Bad Request

You have supplied an IP address which is reserved.

JSON_INVALID 400 Bad Request

We cannot decode the body as a JSON object.

AUTHORIZATION_INVALID 401 Unauthorized

You have supplied an invalid MaxMind user ID and/or license key in the Authorization header.

LICENSE_KEY_REQUIRED 401 Unauthorized

You have not supplied a MaxMind license key in the Authorization header.

USER_ID_REQUIRED 401 Unauthorized

You have not supplied a MaxMind user ID in the Authorization header.

INSUFFICIENT_FUNDS 402 Payment Required

The license key you have provided does not have sufficient funds to use this service. Please purchase more service credits.

PERMISSION_REQUIRED 403 Forbidden

You do not have permission to use the service. Please contact support@maxmind.com for more information.

(none) 403 Forbidden

This status is returned when the request body is larger than 20,000 bytes.

(none) 415 Unsupported Media Type

Your request included a Content-Type header that is not supported. For GET requests, this means the web service cannot return content of that type. For PUT and POST queries, this means the web service cannot parse a request body of that type.

(none) 503 Service Not Available

There is a problem with the web service server. You can try this request again later.

Release Notes

Changes to the minFraud web services are documented in our release notes.

Versioning

The minFraud Score and minFraud Insights web services use two part versions. Our current release is version 2.0. The major version number will remain at 2 for the foreseeable future.

The minor version will only change if there are breaking changes in the web service. A breaking change is one that breaks client code that follows the documentation on this page. Breaking changes include changing the type of an existing field, deleting a field entirely, or changing URIs.

All changes to the web services will be documented in the minFraud release notes, whether or not the version number is changed.

The following changes are not considered to be breaking changes and will not be accompanied by a version number change:

  • Increased validation of inputs that causes a warning to be returned when there previously was not one.
  • Adding a new request or response field, either at the top level of the structure or in one particular object such as the billing or credit_card. Client code should be written to allow for new fields to appear.
  • Adding new values to enum fields such as processor.
  • Adding or removing warning or error codes, and/or changing the body type for an error. Client code should always check the Content-Type header for any error response. Client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.
  • Adding a new service with a new path.

License

These services incorporate Geonames geographical data, which is made available under the Creative Commons Attribution 3.0 License.