Request object

accountobject

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

billingobject

Custom Inputs are optional inputs to the minFraud service that must first be defined for your account. Select “Custom Inputs” from the Account Portal in order to do so. See our Custom Inputs documentation for more information.

deviceobject

This object contains information about the device used in the transaction.

emailobject
eventobject

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

orderobject
paymentobject
shippingobject

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

Request › Account object

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

user_idstring

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.

An MD5 hash as a hexadecimal string of the username or login name associated with the account.

Request › Address object

addressstring

The first line of the user’s billing address.

address_2string

The second line of the user’s billing address.

citystring

The city of the user’s billing address.

companystring

The company of the end user as provided in their billing information.

countrystring

The two character ISO 3166-1 alpha-2 country code of the user’s billing address.

The first name of the end user as provided in their billing information.

last_namestring

The last name of the end user as provided in their billing information.

The country code for phone number associated with the user’s billing address.

The phone number without the country code for the user’s billing address.

postalstring

The postal code of the user’s billing address.

regionstring

The ISO 3166-2 subdivision code for the user’s billing address.

Request › Billing object

addressstring

The first line of the user’s billing address.

address_2string

The second line of the user’s billing address.

citystring

The city of the user’s billing address.

companystring

The company of the end user as provided in their billing information.

countrystring

The two character ISO 3166-1 alpha-2 country code of the user’s billing address.

The first name of the end user as provided in their billing information.

last_namestring

The last name of the end user as provided in their billing information.

The country code for phone number associated with the user’s billing address.

The phone number without the country code for the user’s billing address.

postalstring

The postal code of the user’s billing address.

regionstring

The ISO 3166-2 subdivision code for the user’s billing address.

Request › CreditCard object

The address verification system (AVS) check result, as returned to you by the credit card processor. The minFraud service supports the standard AVS codes.

bank_namestring

The name of the issuing bank as provided by the end user.

The phone country code for the issuing bank as provided by the end user.

The phone number, without the country code, for the issuing bank as provided by the end user.

The card verification value (CVV) code as provided by the payment processor.

The issuer ID number for the credit card. This is the first 6 digits of the credit card number. It identifies the issuing bank.

The last four digits of the credit card number.

tokenstring

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-.

Request › CustomInputs object

Custom Inputs are optional inputs to the minFraud service that must first be defined for your account. Select “Custom Inputs” from the Account Portal in order to do so. See our Custom Inputs documentation for more information.

Request › Device object

This object contains information about the device used in the transaction.

The HTTP “Accept-Language” header of the device used in the transaction.

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.

The HTTP “User-Agent” header of the browser used in the transaction.

Request › Email object

addressstring

This field must be either be a valid email address or an MD5 of the email used in the transaction.

domainstring

The domain of the email address used in the transaction.

Request › Event object

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

shop_idstring

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.

timestring

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.

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.

typestring

The type of event being scored.

Request › Order object

The ID of the affiliate where the order is coming from.

amountnumber (decimal)

The total order amount for the transaction before taxes and discounts.

currencystring

The [ISO 4217 currency code] (http://en.wikipedia.org/wiki/ISO_4217) for the currency used in the transaction.

The discount code applied to the transaction. If multiple discount codes were used, please separate them with a comma.

Whether the purchaser included a gift message.

is_giftboolean

Whether order was marked as a gift by the purchaser.

The URI of the referring site for this order. Needs to be absolute and have a URI scheme such as https://.

The ID of the sub-affiliate where the order is coming from.

Request › Payment object

The decline code as provided by your payment processor. If the transaction was not declined, do not include this field.

processorstring

If your payment processor is missing from this list, please contact [support@maxmind.com}(mailto:support@maxmind.com).

The authorization outcome from the payment processor. If the transaction has not yet been approved or denied, do not include this field.

Request › Shipping object

addressstring

The first line of the user’s billing address.

address_2string

The second line of the user’s billing address.

citystring

The city of the user’s billing address.

companystring

The company of the end user as provided in their billing information.

countrystring

The two character ISO 3166-1 alpha-2 country code of the user’s billing address.

The first name of the end user as provided in their billing information.

last_namestring

The last name of the end user as provided in their billing information.

The country code for phone number associated with the user’s billing address.

The phone number without the country code for the user’s billing address.

postalstring

The postal code of the user’s billing address.

regionstring

The ISO 3166-2 subdivision code for the user’s billing address.

Request › ShoppingCart []

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

arrayarray

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

Request › ShoppingCartItem object

categorystring

The category of the item.

item_idstring

Your internal ID for the item.

pricenumber (decimal)

The per-unit price of this item in the shopping cart. This should use the same currency as the order currency.

quantityinteger

The quantity of the item in the shopping cart.

Response › Factors

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.

funds_remainingnumber (decimal)

The approximate US dollar value of the funds remaining on your MaxMind account.

idstring (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.

queries_remainingnumber (integer)

The approximate number of queries remaining for the service before your account runs out of funds.

risk_scorenumber (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.

Array of warnings.

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.

deviceobject

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

emailobject

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.

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.

Response › Factors › BillingAddress object

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.

The distance in kilometers from the address to the IP location.

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.

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.

latitudenumber (decimal)

The approximate latitude associated with the address.

longitudenumber (decimal)

The approximate longitude associated with the address.

Response › Factors › Device object

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

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.

idstring

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_seenstring

The date and time of the last sighting of the device. The value is formatted according to RFC 3339.

Response › Factors › Email object

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.

The distance in kilometers from the shipping address to billing address.

The distance in kilometers from the address to the IP location.

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.

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.

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.

latitudenumber (decimal)

The approximate latitude associated with the address.

longitudenumber (decimal)

The approximate longitude associated with the address.

Response › Factors › ShippingAddress object

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.

The distance in kilometers from the shipping address to billing address.

The distance in kilometers from the address to the IP location.

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.

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.

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.

latitudenumber (decimal)

The approximate latitude associated with the address.

longitudenumber (decimal)

The approximate longitude associated with the address.

Response › Insights

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.

funds_remainingnumber (decimal)

The approximate US dollar value of the funds remaining on your MaxMind account.

idstring (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.

queries_remainingnumber (integer)

The approximate number of queries remaining for the service before your account runs out of funds.

risk_scorenumber (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.

Array of warnings.

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.

deviceobject

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

emailobject

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.

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.

subscoresobject

Response › Insights › Subscores object

avs_resultnumber (decimal)

The risk associated with the AVS result.

billing_addressnumber (decimal)

The risk associated with the billing address.

The risk associated with the distance between the billing address and the location for the given IP address.

browsernumber (decimal)

The risk associated with the browser attributes such as the User-Agent and Accept-Language.

chargebacknumber (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.

countrynumber (decimal)

The risk associated with the country the transaction originated from.

country_mismatchnumber (decimal)

The risk associated with the combination of IP country, card issuer country, billing country, and shipping country.

cvv_resultnumber (decimal)

The risk associated with the CVV result.

devicenumber (decimal)

The risk associated with the device.

email_addressnumber (decimal)

The risk associated with the device.

email_domainnumber (decimal)

The general risk associated with the email domain.

email_local_partnumber (decimal)

The risk associated with the email address local part (the part of the email address before the @ symbol).

email_tenurenumber (decimal)

Please use email_address instead.

ip_tenurenumber (decimal)

Please use risk_score instead.

issuer_id_numbernumber (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.

order_amountnumber (decimal)

The risk associated with the particular order amount for your account and shop ID.

phone_numbernumber (decimal)

The risk associated with the particular phone number.

shipping_addressnumber (decimal)

The risk associated with the shipping address.

The risk associated with the distance between the shipping address and the location for the given IP address.

time_of_daynumber (decimal)

The risk associated with the local time of day of the transaction in the IP address location.

Response › Score object

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.

funds_remainingnumber (decimal)

The approximate US dollar value of the funds remaining on your MaxMind account.

idstring (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.

queries_remainingnumber (integer)

The approximate number of queries remaining for the service before your account runs out of funds.

risk_scorenumber (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.

Array of warnings.

Response › Score › Disposition object

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.

actionstring

This describes how the request was handled.

reasonstring

This describes why the action was set to a particular value.

Response › Score › IpAddress object

risknumber (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.