minFraud API Requests
Service Endpoints
The endpoint for each service is as specified below.
Service | HTTP Method | Endpoint |
---|---|---|
Score | POST | https://minfraud.maxmind.com/minfraud/v2.0/score |
Insights | POST | https://minfraud.maxmind.com/minfraud/v2.0/insights |
Factors | POST | https://minfraud.maxmind.com/minfraud/v2.0/factors |
The minfraud.maxmind.com hostname automatically picks the data center geographically closest to you.
Headers
The Authorization
header is always required. See
Authorization and Security for more details.
The Accept
header for a request is entirely optional. If you do include one,
you must accept one of the following, substituting the [SERVICE-TYPE]
with
either score
, insights
, or factors
as appropriate:
application/json
application/vnd.maxmind.com-minfraud-[SERVICE TYPE]+json
application/vnd.maxmind.com-minfraud-[SERVICE TYPE]+json; charset=UTF-8; version=2.0
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.
Bodies
minFraud Score, Factors and Insights share the same request body format. Below is a full example of the JSON body document. For detailed explainations of each property within the request body, please refer to the object reference section below.
Object Reference
Below are the schema definitions of that make up the minFraud request body object.
Each schema definition contains a description of an object, along with a list of properties that belong to the object. The following information is listed for each object property:
- name
- type (
array<type>
,boolean
,number
,integer
,object
,string
) - description
- example
- formatting
- constraints (format, min/max, max length, etc.)
- supported services (
Score
,Factors
,Insights
)
Additionally, for object
properties, a link is provided to view a schema
definition that further describes that specific object.
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.
String fields are limited to no more than 255 valid Unicode characters unless a
shorter length is specified; the null and newline characters are 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. Unless it must match a specific format, it is
valid for a string field to be empty.
Boolean fields must be provided as JSON true
or false
.
Unless otherwise specified, if the value meets the requirements for the field, then it will not be modified. Beyond field specific exceptions, an exception to this is if the value is provided as a type different from what we require. In such cases we convert it to the required type if possible. For example, if you provide a string field as a number, then it will be converted to a string, and vice versa. This conversion happens only between numbers and strings.
The entire request body is limited to 20,000 bytes. Requests larger than this size will be rejected.
This object contains account information for the end-user on the site where the event took place.
This object contains information about the email address of the end-user who initiated the event.
This object contains the billing address and contact information provided by the end-user who initiated the event.
This object contains the shipping address and contact information provided by the end-user who initiated the event.
This object contains information from and about the payment process that was used for the event.
This object contains information provided by the end-user and the payment processor about the credit card used for the for the event.
This is an array of shopping cart item objects. A shopping cart should consist of an array of one or more item objects.
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.
This object contains information about 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.
Get tips for how to pass the /device/ip_address
input on our Knowledge
Base.
The HTTP User-Agent
header of the browser used in the transaction.
Learn more about the /device/user_agent
input on our Knowledge
Base.
The HTTP Accept-Language
header of the device used in the transaction.
Learn more about the /device/accept_language
input on our Knowledge
Base.
The number of seconds between the creation of the user's session and the
time of the transaction. Note that session_age
is not the duration of the
current visit, but the time since the start of the first visit.
Learn more about the /device/session_age
input on our Knowledge
Base.
An ID that uniquely identifies a visitor's session on the site.
Learn more about the /device/session_id
input on our Knowledge
Base.
This object contains general information related to the event being scored.
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. No specific format is required.
Learn more about the /event/transaction_id
input on our Knowledge
Base.
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. No specific format is required.
Learn more about the /event/shop_id
input on our Knowledge
Base.
The date and time the event occurred. The string must be in the RFC 3339 date-time format. The time must be within the past year. If this field is not in the request, the current time will be used.
It is not recommended to use this input when scoring live transactions as they occur. However, it can be useful if you store transactions to be submitted to the service for scoring later.
Please note that you cannot submit times more than one year in the past. If you submit an event time more than one year in the past, the current time will be used to score the transaction, and a warning will be returned.
Learn more about the /event/time
input on our Knowledge
Base.
The type of event being scored. The valid types are:
account_creation
account_login
email_change
password_reset
payout_change
purchase
recurring_purchase
referral
survey
Learn more about the
/event/type
input on our Knowledge Base.
This object contains account information for the end-user on the site where the event took place.
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 account ID. No specific format is required.
Learn more about the /account/user_id
input on our Knowledge
Base.
An MD5 hash as a hexadecimal string of the username or login name associated with the account.
This object contains information about the email address of the end-user who initiated the event.
This field must be either be a valid email address or an MD5 of the email used in the transaction.
Learn more about the /email/address
input on our Knowledge
Base.
The domain of the email address used in the transaction. Do not include the
@
in this field.
You do not need to pass the email domain input unless you are passing the email address as an MD5 hash. Learn more about hashed email inputs on our Knowledge Base.
This object contains the billing address and contact information provided by the end-user who initiated the event.
Learn more about the billing address inputs on our Knowledge Base.
The two character ISO 3166-1 alpha-2 country code of the user's billing address.
The phone number without the country code for the user's billing address. Punctuation characters will be stripped. After stripping punctuation characters, the number must contain only digits.
The country code for phone number associated with the user's billing address. If you provide this information then you must provide at least one digit.
This object contains the shipping address and contact information provided by the end-user who initiated the event.
Learn more about the shipping address inputs on our Knowledge Base.
The two character ISO 3166-1 alpha-2 country code of the user's shipping address.
The phone number without the country code for the user's shipping address. Punctuation characters will be stripped. After stripping punctuation characters, the number must contain only digits.
The country code for phone number associated with the user's shipping address. If you provide this information then you must provide at least one digit.
The shipping delivery speed for the order. The valid values are:
same_day
overnight
expedited
standard
This object contains information from and about the payment process that was used for the event.
The payment processor used for the transaction. The valid values are:
adyen
affirm
afterpay
altapay
amazon_payments
american_express_payment_gateway
apple_pay
aps_payments
authorizenet
balanced
beanstream
bluepay
bluesnap
boacompra
boku
bpoint
braintree
cardknox
cardpay
cashfree
ccavenue
ccnow
cetelem
chase_paymentech
checkout_com
cielo
collector
commdoo
compropago
concept_payments
conekta
coregateway
creditguard
credorax
ct_payments
cuentadigital
curopayments
cybersource
dalenys
dalpay
datacap
datacash
dibs
digital_river
dlocal
dotpay
ebs
ecomm365
ecommpay
elavon
emerchantpay
epay
eprocessing_network
epx
eway
exact
first_atlantic_commerce
first_data
fiserv
g2a_pay
global_payments
gocardless
google_pay
heartland
hipay
ingenico
interac
internetsecure
intuit_quickbooks_payments
iugu
klarna
komoju
lemon_way
mastercard_payment_gateway
mercadopago
mercanet
merchant_esolutions
mirjeh
mollie
moneris_solutions
neopay
neosurf
nmi
oceanpayment
oney
onpay
openbucks
openpaymx
optimal_payments
orangepay
other
pacnet_services
payconex
payeezy
payfast
paygate
paylike
payment_express
paymentwall
payone
paypal
payplus
paysafecard
paysera
paystation
paytm
paytrace
paytrail
payture
payulatam
payvision
payu
payway
payza
pinpayments
placetopay
posconnect
princeton_payment_solutions
psigate
pxp_financial
qiwi
quickpay
raberil
razorpay
rede
redpagos
rewardspay
safecharge
sagepay
securetrading
shopify_payments
simplify_commerce
skrill
smartcoin
smartdebit
solidtrust_pay
sps_decidir
stripe
synapsefi
systempay
telerecargas
towah
transact_pro
trustly
trustpay
tsys
usa_epay
vantiv
verepay
vericheck
vindicia
virtual_card_services
vme
vpos
windcave
wirecard
worldpay
If your payment processor is missing from this list, please contact 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.
The decline code as provided by your payment processor. If the transaction was not declined, do not include this field.
This object contains information provided by the end-user and the payment processor about the credit card used for the for the event.
The issuer ID number for the credit card. This is the first six or eight digits of the credit card number. It identifies the issuing bank. If you do not know whether the IIN is six or eight digits long, send us six digits.
Learn more about the /credit_card/issuer_id_number
input on our Knowledge
Base.
The last digits of the credit card number. In most cases, you should send
the last four digits for last_digits
. If you send an
issuer_id_number
that contains an eight digit IIN, and if the credit card brand is not one
of the following, you should send the last two digits for last_digits
:
Discover
, JCB
, Mastercard
, UnionPay
, Visa
.
Learn more about the /credit_card/last_digits
input on our Knowledge
Base.
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-
.
Learn more about the /credit_card/token
input on our Knowledge
Base.
The phone country code for the issuing bank as provided by the end user. If you provide this information then you must provide at least one digit.
The phone number, without the country code, for the issuing bank as provided by the end user. Punctuation characters will be stripped. After stripping punctuation characters, the number must contain only digits.
The two character ISO 3166-1 alpha-2 country
code where the issuer of
the card is located. This may be passed instead of the
issuer_id_number
if
you do not wish to pass partial account numbers, or if your payment
processor does not provide them.
Learn more about the /credit_card/country
input on our Knowledge
Base.
The address verification system (AVS) check result, as returned to you by the credit card processor. The minFraud service supports the standard AVS codes.
Learn more about the /credit_card/avs_result
input on our Knowledge
Base.
The card verification value (CVV) code as provided by the payment processor.
Learn more about the /credit_card/cvv_result
input on our Knowledge
Base.
Whether the outcome of 3-D Secure verification (e.g. Safekey, SecureCode,
Verified by Visa) was successful. true
if customer verification was
successful, or false
if the customer failed verification. If 3-D Secure
verification was not used, was unavailable, or resulted in another outcome
other than success or failure, do not include this field.
Learn more about the /credit_card/was_3d_secure_successfil
input on our
Knowledge Base.
This object contains information about the order associated with the event.
The total order amount for the transaction before taxes and discounts.
Learn more about the /order/amount
input on our Knowledge
Base.
The ISO 4217 currency code for the currency used in the transaction.
Learn more about the /order/currency
input on our Knowledge
Base.
The discount code applied to the transaction. If multiple discount codes were used, please separate them with a comma.
Learn more about the /order/discount_code
input on our Knowledge
Base.
The ID of the affiliate where the order is coming from. No specific format is required.
Learn more about the /order/affiliate_id
input on our Knowledge
Base.
The ID of the sub-affiliate where the order is coming from. No specific format is required.
Learn more about the /order/subaffiliate_id
input on our Knowledge
Base.
The URI of the referring site for this order. Needs to be absolute and have
a URI scheme such as https://
.
Learn more about the /order/referrer_uri
input on our Knowledge
Base.
Whether order was marked as a gift by the purchaser.
Learn more about the /order/is_gift
input on our Knowledge
Base.
Whether the purchaser included a gift message.
Learn more about the /order/has_gift_message
input on our Knowledge
Base.
This is an array of shopping cart item objects. A shopping cart should consist of an array of one or more item objects.
Learn more about the shopping cart inputs on our Knowledge Base.
This object contains information about an item from the end-user's shopping cart associated with the event
Your internal ID for the item. No specific format is required. This can also be a hashed value; see below.
The quantity of the item in the shopping cart. The value must be a whole number.
The per-unit price of this item in the shopping cart. This should use the same currency as the order currency.
Passing hashed values for shopping cart items can increase the privacy of your customers' information while continuing to fulfill the needs for fraud detection. A suitable hashed value can be produced by using a cryptographic hash function and a fixed salt. Using a random salt is not recommended as that will result in different hashed values for the same plain value, which would make them ineffective for our fraud detection service. For more information, see:
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.
You should never send a full credit card number as an input. If you attempt to send a full credit card number as an input, the minFraud service will reject the input and issue a warning.
A custom key of your choice with a string value, formatted as a phone number. Numbers, spaces and punctuation accepted, although spaces and punctuation will be stripped. The following ASCII characters constitute the accepted punctuation: ` ~ ! @ # $ % ^ & * ( ) – _ = + ‘ ” ; : , < . > / ? \ | [ ] { and }.
A custom key of your choice with a string value. The null character is not allowed.
This page was last updated on September 12, 2024.