minFraud Python API¶

Description¶

This package provides an API for the MaxMind minFraud Score, Insights, and Factors web services as well as the Report Transaction web service.

Installation¶

To install the minfraud module, type:

$ pip install minfraud

If you are not able to install from PyPI, you may also use pip from the source directory:

$ python -m pip install .

Documentation¶

Complete API documentation is available on Read the Docs.

Usage¶

To use this API, create a new minfraud.Client object for a synchronous request or minfraud.AsyncClient for an asynchronous request. The constructors take your MaxMind account ID and license key:

>>> client = Client(42, 'licensekey')
>>> async_client = AsyncClient(42, 'licensekey')

To use the Sandbox web service instead of the production web service, you can provide the host argument:

>>> client = Client(42, 'licensekey', 'sandbox.maxmind.com')
>>> async_client = AsyncClient(42, 'licensekey', 'sandbox.maxmind.com')

Score, Insights and Factors Usage¶

The Factors service is called with the factors() method:

>>> client.factors({'device': {'ip_address': '152.216.7.110'}})
>>> await async_client.factors({'device': {'ip_address': '152.216.7.110'}})

The Insights service is called with the insights() method:

>>> client.insights({'device': {'ip_address': '152.216.7.110'}})
>>> await async_client.insights({'device': {'ip_address': '152.216.7.110'}})

The Score web service is called with the score() method:

>>> client.score({'device': {'ip_address': '152.216.7.110'}})
>>> await async_client.score({'device': {'ip_address': '152.216.7.110'}})

Each of these methods takes a dictionary representing the transaction to be sent to the web service. The structure of this dictionary should be in the format specified in the REST API documentation. All fields are optional.

Report Transactions Usage¶

MaxMind encourages the use of this API as data received through this channel is used to continually improve the accuracy of our fraud detection algorithms. The Report Transaction web service is called with the report() method:

>>> client.report({'ip_address': '152.216.7.110', 'tag': 'chargeback'})
>>> await async_client.report({'ip_address': '152.216.7.110', 'tag': 'chargeback'})

The method takes a dictionary representing the report to be sent to the web service. The structure of this dictionary should be in the format specified in the REST API documentation. The required fields are tag and one or more of the following: ip_address, maxmind_id, minfraud_id, transaction_id.

Request Validation (for all request methods)¶

Assuming validation has not been disabled, before sending the transaction to the web service, the transaction dictionary structure and content will be validated. If validation fails, a minfraud.InvalidRequestError will be raised.

If the dictionary is valid, a request will be made to the web service. If the request succeeds, a model object for the service response will be returned. If the request fails, one of the errors listed below will be raised.

Errors¶

The possible errors are:

minfraud.AuthenticationError - This will be raised when the server is unable to authenticate the request, e.g., if the license key or account ID is invalid.
minfraud.InvalidRequestError - This will be raised when the server rejects the request as invalid for another reason, such as a reserved IP address. It is also raised if validation of the request before it is sent to the server fails.
minfraud.HttpError - This will be raised when an unexpected HTTP error occurs such as a firewall interfering with the request to the server.
minfraud.MinFraudError - This will be raised when some other error occurs such as unexpected content from the server. This also serves as the base class for the above errors.

Additionally, score, insights and factors may also raise:

minfraud.InsufficientFundsError - This will be raised when your account is out of funds.

Examples¶

Score, Insights and Factors Example¶

>>> import asyncio
>>> from minfraud import AsyncClient, Client
>>>
>>> request = {
>>>     'device': {
>>>         'ip_address': '152.216.7.110',
>>>         'accept_language': 'en-US,en;q=0.8',
>>>         'session_age': 3600,
>>>         'session_id': 'a333a4e127f880d8820e56a66f40717c',
>>>         'tracking_token': '...',
>>>         'user_agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36'
>>>     },
>>>     'event': {
>>>         'party': 'customer',
>>>         'shop_id': 's2123',
>>>         'type': 'purchase',
>>>         'transaction_id': 'txn3134133',
>>>         'time': '2014-04-12T23:20:50.052+00:00'
>>>     },
>>>     'account': {
>>>         'user_id': '3132',
>>>         'username_md5': '570a90bfbf8c7eab5dc5d4e26832d5b1'
>>>     },
>>>     'email': {
>>>         'address': '977577b140bfb7c516e4746204fbdb01',
>>>         'domain': 'maxmind.com'
>>>     },
>>>     'billing': {
>>>         'first_name': 'Jane',
>>>         'last_name': 'Doe',
>>>         'company': 'Company',
>>>         'address': '101 Address Rd.',
>>>         'address_2': 'Unit 5',
>>>         'city': 'Hamden',
>>>         'region': 'CT',
>>>         'country': 'US',
>>>         'postal': '06510',
>>>         'phone_country_code': '1',
>>>         'phone_number': '123-456-7890',
>>>     },
>>>     'shipping': {
>>>         'first_name': 'John',
>>>         'last_name': 'Doe',
>>>         'company': 'ShipCo',
>>>         'address': '322 Ship Addr. Ln.',
>>>         'address_2': 'St. 43',
>>>         'city': 'New Haven',
>>>         'region': 'CT',
>>>         'country': 'US',
>>>         'postal': '06510',
>>>         'phone_country_code': '1',
>>>         'phone_number': '123-456-0000',
>>>         'delivery_speed': 'same_day',
>>>     },
>>>     'credit_card': {
>>>         'bank_phone_country_code': '1',
>>>         'avs_result': 'Y',
>>>         'bank_phone_number': '123-456-1234',
>>>         'last_digits': '7643',
>>>         'cvv_result': 'N',
>>>         'bank_name': 'Bank of No Hope',
>>>         'issuer_id_number': '411111',
>>>         'token': '123456abc1234',
>>>         'was_3d_secure_successful': True
>>>     },
>>>     'payment': {
>>>         'decline_code': 'invalid number',
>>>         'was_authorized': False,
>>>         'method': 'card',
>>>         'processor': 'stripe'
>>>     },
>>>     'shopping_cart': [{
>>>         'category': 'pets',
>>>         'quantity': 2,
>>>         'price': 20.43,
>>>         'item_id': 'lsh12'
>>>     }, {
>>>         'category': 'beauty',
>>>         'quantity': 1,
>>>         'price': 100.0,
>>>         'item_id': 'ms12'
>>>     }],
>>>     'order': {
>>>         'affiliate_id': 'af12',
>>>         'referrer_uri': 'http://www.amazon.com/',
>>>         'subaffiliate_id': 'saf42',
>>>         'discount_code': 'FIRST',
>>>         'currency': 'USD',
>>>         'amount': 323.21,
>>>         'is_gift': True,
>>>         'has_gift_message': True
>>>      },
>>>     'custom_inputs': {
>>>         'section': 'news',
>>>         'num_of_previous_purchases': 19,
>>>         'discount': 3.2,
>>>         'previous_user': True
>>>     }
>>> }
>>>
>>> # This example function uses a synchronous Client object. The object
>>> # can be used across multiple requests.
>>> def client(account_id, license_key):
>>>     with Client(account_id, license_key) as client:
>>>
>>>         print(client.score(request))
Score(...)
>>>
>>>         print(client.insights(request))
Insights(...)
>>>
>>>         print(client.factors(request))
Factors(...)
>>>
>>> # This example function uses an asynchronous AsyncClient object. The
>>> # object can be used across multiple requests.
>>> async def async_client(account_id, license_key):
>>>     async with AsyncClient(account_id, license_key) as client:
>>>
>>>         print(await client.score(request))
Score(...)
>>>
>>>         print(await client.insights(request))
Insights(...)
>>>
>>>         print(await client.factors(request))
Factors(...)
>>>
>>> client(42, 'license_key')
>>> asyncio.run(async_client(42, 'license_key'))

Report Transactions Example¶

For synchronous reporting:

>>> from minfraud import Client
>>>
>>> with Client(42, 'licensekey') as client
>>>     transaction_report = {
>>>         'ip_address': '152.216.7.110',
>>>         'tag': 'chargeback',
>>>         'minfraud_id': '2c69df73-01c0-45a5-b218-ed85f40b17aa',
>>>      }
>>>      client.report(transaction_report)

For asynchronous reporting:

>>> import asyncio
>>> from minfraud import AsyncClient
>>>
>>> async def report():
>>>     async with AsyncClient(42, 'licensekey') as client
>>>         transaction_report = {
>>>             'ip_address': '152.216.7.110',
>>>             'tag': 'chargeback',
>>>             'minfraud_id': '2c69df73-01c0-45a5-b218-ed85f40b17aa',
>>>          }
>>>          await async_client.report(transaction_report)
>>>
>>> asyncio.run(report())

Versioning¶

The minFraud Python API uses Semantic Versioning.

Support¶

Please report all issues with this code using the GitHub issue tracker.

If you are having an issue with a MaxMind service that is not specific to the client API, please contact MaxMind support for assistance.

Copyright and License¶

This is free software, licensed under the Apache License, Version 2.0.

Web Service Client¶

minFraud client module.

Client for minFraud Score, Insights, and Factors.

class minfraud.webservice.AsyncClient(account_id: int, license_key: str, host: str = 'minfraud.maxmind.com', locales: Sequence[str] = ('en',), timeout: float = 60, proxy: str | None = None)¶

Bases: BaseClient

Async client for accessing the minFraud web services.

Construct AsyncClient.

Parameters:

account_id (int) – Your MaxMind account ID
license_key (str) – Your MaxMind license key
host (str) – The host to use when connecting to the web service.
locales (tuple[str]) – A tuple of locale codes to use in name property
timeout (float) – The timeout in seconds to use when waiting on the request. This sets both the connect timeout and the read timeout. The default is 60.
proxy – The URL of an HTTP proxy to use. It may optionally include a basic auth username and password, e.g., http://username:password@host:port.

Returns:

Client object

Return type:

Client

async close() → None¶

Close underlying session.

This will close the session and any associated connections.

async factors(transaction: dict[str, Any], validate: bool = True, hash_email: bool = False) → Factors¶

Query Factors endpoint with transaction data.

Parameters:

transaction (dict) – A dictionary containing the transaction to be sent to the minFraud Factors web service as specified in the REST API documentation.
validate (bool) – If set to false, validation of the transaction dictionary will be disabled. This validation helps ensure that your request is correct before sending it to MaxMind. Validation raises an InvalidRequestError.
hash_email (bool) – By default, the email address is sent in plain text. If this is set to True, the email address will be normalized and converted to an MD5 hash before the request is sent. The email domain will continue to be sent in plain text.

Returns:

A Factors model object

Return type:

Factors

Raises:

AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

async insights(transaction: dict[str, Any], validate: bool = True, hash_email: bool = False) → Insights¶

Query Insights endpoint with transaction data.

Parameters:

transaction (dict) –
A dictionary containing the transaction to be sent to the minFraud Insights web service as specified in the REST API documentation.
validate (bool) – If set to false, validation of the transaction dictionary will be disabled. This validation helps ensure that your request is correct before sending it to MaxMind. Validation raises an InvalidRequestError.
hash_email (bool) – By default, the email address is sent in plain text. If this is set to True, the email address will be normalized and converted to an MD5 hash before the request is sent. The email domain will continue to be sent in plain text.

Returns:

An Insights model object

Return type:

Insights

Raises:

AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

async report(report: dict[str, str | None], validate: bool = True) → None¶

Send a transaction report to the Report Transaction endpoint.

Parameters:

report (dict) – A dictionary containing the transaction report to be sent to the Report Transations web service as specified in the REST API documentation <https://dev.maxmind.com/minfraud/report-a-transaction?lang=en>_.
validate (bool) – If set to false, validation of the report dictionary will be disabled. This validation helps ensure that your request is correct before sending it to MaxMind. Validation raises an InvalidRequestError.

Returns:

Nothing

Return type:

None

Raises:

AuthenticationError, InvalidRequestError, HTTPError, MinFraudError,

async score(transaction: dict[str, Any], validate: bool = True, hash_email: bool = False) → Score¶

Query Score endpoint with transaction data.

Parameters:

transaction (dict) –
A dictionary containing the transaction to be sent to the minFraud Score web service as specified in the REST API documentation.
validate (bool) – If set to false, validation of the transaction dictionary will be disabled. This validation helps ensure that your request is correct before sending it to MaxMind. Validation raises an InvalidRequestError.
hash_email (bool) – By default, the email address is sent in plain text. If this is set to True, the email address will be normalized and converted to an MD5 hash before the request is sent. The email domain will continue to be sent in plain text.

Returns:

A Score model object

Return type:

Score

Raises:

AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

class minfraud.webservice.BaseClient(account_id: int, license_key: str, host: str = 'minfraud.maxmind.com', locales: Sequence[str] = ('en',), timeout: float = 60)¶

Bases: object

Base class for minFraud clients.

Initialize the base client.

class minfraud.webservice.Client(account_id: int, license_key: str, host: str = 'minfraud.maxmind.com', locales: Sequence[str] = ('en',), timeout: float = 60, proxy: str | None = None)¶

Bases: BaseClient

Synchronous client for accessing the minFraud web services.

Construct Client.

Parameters:

account_id (int) – Your MaxMind account ID
license_key (str) – Your MaxMind license key
host (str) – The host to use when connecting to the web service. By default, the client connects to the production host. However, during testing and development, you can set this option to ‘sandbox.maxmind.com’ to use the Sandbox environment’s host. The sandbox allows you to experiment with the API without affecting your production data.
locales (tuple[str]) – A tuple of locale codes to use in name property
timeout (float) – The timeout in seconds to use when waiting on the request. This sets both the connect timeout and the read timeout. The default is 60.
proxy – The URL of an HTTP proxy to use. It may optionally include a basic auth username and password, e.g., http://username:password@host:port.

Returns:

Client object

Return type:

Client

close() → None¶

Close underlying session.

This will close the session and any associated connections.

factors(transaction: dict[str, Any], validate: bool = True, hash_email: bool = False) → Factors¶

Query Factors endpoint with transaction data.

Parameters:

transaction (dict) –
A dictionary containing the transaction to be sent to the minFraud Factors web service as specified in the REST API documentation.
validate (bool) – If set to false, validation of the transaction dictionary will be disabled. This validation helps ensure that your request is correct before sending it to MaxMind. Validation raises an InvalidRequestError.
hash_email (bool) – By default, the email address is sent in plain text. If this is set to True, the email address will be normalized and converted to an MD5 hash before the request is sent. The email domain will continue to be sent in plain text.

Returns:

A Factors model object

Return type:

Factors

Raises:

AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

insights(transaction: dict[str, Any], validate: bool = True, hash_email: bool = False) → Insights¶

Query Insights endpoint with transaction data.

Parameters:

transaction (dict) –
A dictionary containing the transaction to be sent to the minFraud Insights web service as specified in the REST API documentation.
validate (bool) – If set to false, validation of the transaction dictionary will be disabled. This validation helps ensure that your request is correct before sending it to MaxMind. Validation raises an InvalidRequestError.
hash_email (bool) – By default, the email address is sent in plain text. If this is set to True, the email address will be normalized and converted to an MD5 hash before the request is sent. The email domain will continue to be sent in plain text.

Returns:

An Insights model object

Return type:

Insights

Raises:

AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

report(report: dict[str, str | None], validate: bool = True) → None¶

Send a transaction report to the Report Transaction endpoint.

Parameters:

report (dict) – A dictionary containing the transaction report to be sent to the Report Transations web service as specified in the REST API documentation <https://dev.maxmind.com/minfraud/report-transaction/#Request_Body>_.
validate (bool) – If set to false, validation of the report dictionary will be disabled. This validation helps ensure that your request is correct before sending it to MaxMind. Validation raises an InvalidRequestError.

Returns:

Nothing

Return type:

None

Raises:

AuthenticationError, InvalidRequestError, HTTPError, MinFraudError,

score(transaction: dict[str, Any], validate: bool = True, hash_email: bool = False) → Score¶

Query Score endpoint with transaction data.

Parameters:

transaction (dict) –
A dictionary containing the transaction to be sent to the minFraud Score web service as specified in the REST API documentation.
validate (bool) – If set to false, validation of the transaction dictionary will be disabled. This validation helps ensure that your request is correct before sending it to MaxMind. Validation raises an InvalidRequestError.
hash_email (bool) – By default, the email address is sent in plain text. If this is set to True, the email address will be normalized and converted to an MD5 hash before the request is sent. The email domain will continue to be sent in plain text.

Returns:

A Score model object

Return type:

Score

Raises:

AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

Response Models¶

Models for the minFraud response object.

Bases: _Serializable

Information about the billing address.

Initialize a BillingAddress instance.

distance_to_ip_location: int | None¶: The distance in kilometers from the address to the IP location.

is_in_ip_country: bool | None¶: This property is True if the address is in the IP country. The property is False when the address is not in the IP country. If the address could not be parsed or was not provided or if the IP address could not be geolocated, the property will be None.

is_postal_in_city: bool | None¶: This property is True if the postal code provided with the address is in the city for the address. The property is False when the postal code is not in the city. If the address was not provided, could not be parsed, or was outside USA, the property will be None.

latitude: float | None¶: The latitude associated with the address.

longitude: float | None¶: The longitude associated with the address.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

Bases: _Serializable

Information about the credit card based on the issuer ID number.

Initialize a CreditCard instance.

brand: str | None¶: The card brand, such as “Visa”, “Discover”, “American Express”, etc.

country: str | None¶: This property contains the 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_business: bool | None¶: This property is True if the card is a business card.

is_issued_in_billing_address_country: bool | None¶: This property is true if the country of the billing address matches the country of the majority of customers using this credit card. In cases where the location of customers is highly mixed, the match is to the country of the bank issuing the card.

is_prepaid: bool | None¶: This property is True if the card is a prepaid card.

is_virtual: bool | None¶: This property is True if the card is a virtual card.

issuer: Issuer¶: An object containing information about the credit card issuer.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

type: str | None¶: The card’s type. The valid values are “charge”, “credit”, and “debit”. See Wikipedia for an explanation of the difference between charge and credit cards.

class minfraud.models.Device(*, confidence: float | None = None, id: str | None = None, last_seen: str | None = None, local_time: str | None = None, **_: Any)¶

Bases: _Serializable

Information about the device associated with the IP address.

In order to receive device output from minFraud Insights or minFraud Factors, you must be using the Device Tracking Add-on.

Initialize a Device instance.

confidence: float | None¶: This number represents our 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: str | None¶: A UUID that MaxMind uses for the device associated with this IP address.

last_seen: str | None¶: This is the date and time of the last sighting of the device. This is an RFC 3339 date-time.

local_time: str | None¶: This is the local date and time of the transaction in the time zone of the device. This is determined by using the UTC offset associated with the device. This is an RFC 3339 date-time.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

class minfraud.models.Disposition(*, action: str | None = None, reason: str | None = None, rule_label: str | None = None, **_: Any)¶

Bases: _Serializable

Information about disposition for the request as set by custom rules.

In order to receive a disposition, you must be use the minFraud custom rules.

Initialize a Disposition instance.

action: str | None¶: The action to take on the transaction as defined by your custom rules. The current set of values are “accept”, “manual_review”, “reject”, and “test”. If you do not have custom rules set up, None will be returned.

reason: str | None¶: The reason for the action. The current possible values are “custom_rule” and “default”. If you do not have custom rules set up, None will be returned.

rule_label: str | None¶: The label of the custom rule that was triggered. If you do not have custom rules set up, the triggered custom rule does not have a label, or no custom rule was triggered, None will be returned.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

Bases: _Serializable

Information about the email address passed in the request.

Initialize an Email instance.

domain: EmailDomain¶: An object containing information about the email domain.

first_seen: str | None¶: A date string (e.g. 2017-04-24) to identify the date an email address was first seen by MaxMind. This is expressed using the ISO 8601 date format.

is_disposable: bool | None¶: This field indicates whether the email is from a disposable email provider. It will be None when an email address was not passed in the inputs.

is_free: bool | None¶: 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: bool | None¶: 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.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

Bases: _Serializable

Information about the email domain passed in the request.

Initialize an EmailDomain instance.

classification: str | None¶: A classification of the domain. This will be one of the following values: business, education, government, or isp_email. Additional values may be added in the future.

first_seen: str | None¶: A date string (e.g. 2017-04-24) to identify the date an email domain was first seen by MaxMind. This is expressed using the ISO 8601 date format.

risk: float | None¶: This field contains the risk associated with the domain. The value ranges from 0.01 to 99. A higher score indicates higher risk.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

visit: EmailDomainVisit¶: An object containing information from an automated visit to the email domain. This object may be populated after an automated visit has been completed. For newly sighted domains, the visit information may take some time to appear. Visit information is limited to low-volume domains only.

volume: float | None¶: This field indicates the activity on an email domain across the minFraud network, expressed in sightings per million. The value ranges from 0.001 to 1,000,000. Values are rounded to 2 significant figures.

class minfraud.models.EmailDomainVisit(*, status: str | None = None, last_visited_on: str | None = None, has_redirect: bool | None = None, **_: Any)¶

Bases: _Serializable

Information from an automated visit to the email domain.

Initialize an EmailDomainVisit instance.

has_redirect: bool | None¶: This is True if the domain in the request has redirects (configured to automatically send visitors to another URL). Otherwise the key is omitted. When True, the status corresponds to the final redirected domain.

last_visited_on: str | None¶: A date string (e.g. 2019-01-01) to identify the date when the automated visit to the domain was completed. This is expressed using the ISO 8601 date format YYYY-MM-DD.

status: str | None¶: A classification of the status of the domain based on an automated visit. This will be one of the following values: live, dns_error, network_error, http_error, parked, or pre_development. Additional values may be added in the future.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

class minfraud.models.Factors(locales: Sequence[str], *, billing_address: dict[str, Any] | None = None, billing_phone: dict[str, Any] | None = None, credit_card: dict[str, Any] | None = None, disposition: dict[str, Any] | None = None, funds_remaining: float, device: dict[str, Any] | None = None, email: dict[str, Any] | None = None, id: str, ip_address: dict[str, Any] | None = None, queries_remaining: int, risk_score: float, shipping_address: dict[str, Any] | None = None, shipping_phone: dict[str, Any] | None = None, subscores: dict[str, Any] | None = None, warnings: list[dict[str, Any]] | None = None, risk_score_reasons: list[dict[str, Any]] | None = None, **_: Any)¶

Bases: _Serializable

Model for Factors response.

Initialize a Factors instance.

billing_address: BillingAddress¶: A BillingAddress object containing minFraud data related to the billing address used in the transaction.

billing_phone: Phone¶: A Phone object containing minFraud data related to the billing phone used in the transaction.

credit_card: CreditCard¶: A CreditCard object containing minFraud data about the credit card used in the transaction.

device: Device¶: A Device object containing information about the device that MaxMind believes is associated with the IP address passed in the request.

disposition: Disposition¶: A Disposition object containing the disposition for the request as set by custom rules.

email: Email¶: A Email object containing information about the email address passed in the request.

funds_remaining: float¶: The approximate US dollar value of the funds remaining on your MaxMind account.

id: str¶: This is a UUID that identifies the minFraud request. Please use this ID in bug reports or support requests to MaxMind so that we can easily identify a particular request.

ip_address: IPAddress¶: A IPAddress object containing GeoIP and minFraud Insights information about the IP address.

queries_remaining: int¶: The approximate number of queries remaining on this service before your account runs out of funds.

risk_score: float¶: This property 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.

risk_score_reasons: list[RiskScoreReason]¶: This list contains RiskScoreReason objects that describe risk score reasons for a given transaction that change the risk score significantly. Risk score reasons are usually only returned for medium to high risk transactions. If there were no significant changes to the risk score due to these reasons, then this list will be empty.

shipping_address: ShippingAddress¶: A ShippingAddress object containing minFraud data related to the shipping address used in the transaction.

shipping_phone: Phone¶: A Phone object containing minFraud data related to the shipping phone used in the transaction.

subscores: Subscores¶: A Subscores object containing scores for many of the individual risk factors that are used to calculate the overall risk score.

Deprecated since version 2.12.0: Use RiskScoreReason instead.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

warnings: list[ServiceWarning]¶: This list contains ServiceWarning objects detailing issues with the request that was sent such as invalid or unknown inputs. It is highly recommended that you check this list for issues when integrating the web service.

class minfraud.models.GeoIP2Location(*args: Any, **kwargs: Any)¶

Bases: Location

Location information for the IP address.

In addition to the attributes provided by geoip2.records.Location, this class provides the local_time attribute.

Initialize a GeoIP2Location instance.

accuracy_radius: int | None¶: The approximate accuracy radius in kilometers around the latitude and longitude for the IP address. This is the radius where we have a 67% confidence that the device using the IP address resides within the circle centered at the latitude and longitude with the provided radius.

average_income: int | None¶: The average income in US dollars associated with the requested IP address. This attribute is only available from the Insights end point.

latitude: float | None¶: 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.

local_time: str | None¶: 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.

longitude: float | None¶: 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.

metro_code: int | None¶: The metro code is a no-longer-maintained code for targeting advertisements in Google.

Deprecated since version 4.9.0.

population_density: int | None¶: The estimated population per square kilometer associated with the IP address. This attribute is only available from the Insights end point.

time_zone: str | None¶: The time zone associated with location, as specified by the IANA Time Zone Database, e.g., “America/New_York”.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

Bases: Insights

Model for minFraud and GeoIP data about the IP address.

This class inherits from geoip2.models.Insights. In addition to the attributes provided by that class, it provides the risk and risk_reasons attributes. It also overrides the location attribute to use GeoIP2Location.

Initialize an IPAddress instance.

anonymizer: Anonymizer¶: Anonymizer object for the requested IP address. This object contains information about VPN and proxy usage.

city: City¶: City object for the requested IP address.

continent: Continent¶: Continent object for the requested IP address.

country: Country¶: Country object for the requested IP address. This record represents the country where MaxMind believes the IP is located.

location: GeoIP2Location¶: Location object for the requested IP address.

maxmind: MaxMind¶: Information related to your MaxMind account.

postal: Postal¶: Postal object for the requested IP address.

registered_country: Country¶: The registered country object for the requested IP address. This record represents the country where the ISP has registered a given IP block in and may differ from the user’s country.

represented_country: RepresentedCountry¶: Object for the country represented by the users of the IP address when that country is different than the country in country. For instance, the country represented by an overseas military base.

risk: float | None¶: 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.

risk_reasons: list[IPRiskReason]¶: This list contains IPRiskReason objects identifying the reasons why the IP address received the associated risk. This will be an empty list if there are no reasons.

subdivisions: Subdivisions¶: Object (tuple) representing the subdivisions of the country to which the location of the requested IP address belongs.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

traits: Traits¶: Object with the traits of the requested IP address.

class minfraud.models.IPRiskReason(code: str | None = None, reason: str | None = None)¶

Bases: _Serializable

Reason for the IP risk.

This class provides both a machine-readable code and a human-readable explanation of the reason for the IP risk score.

Although more codes may be added in the future, the current codes are:

ANONYMOUS_IP - The IP address belongs to an anonymous network. See the object at ->ipAddress->traits for more details.
BILLING_POSTAL_VELOCITY - Many different billing postal codes have been seen on this IP address.
EMAIL_VELOCITY - Many different email addresses have been seen on this IP address.
HIGH_RISK_DEVICE - A high risk device was seen on this IP address.
HIGH_RISK_EMAIL - A high risk email address was seen on this IP address in your past transactions.
ISSUER_ID_NUMBER_VELOCITY - Many different issuer ID numbers have been seen on this IP address.
MINFRAUD_NETWORK_ACTIVITY - Suspicious activity has been seen on this IP address across minFraud customers.

Initialize an IPRiskReason instance.

code: str | None¶: This value is a machine-readable code identifying the reason.

reason: str | None¶: This property provides a human-readable explanation of the reason. The text may change at any time and should not be matched against.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

class minfraud.models.Insights(locales: Sequence[str], *, billing_address: dict[str, Any] | None = None, billing_phone: dict[str, Any] | None = None, credit_card: dict[str, Any] | None = None, device: dict[str, Any] | None = None, disposition: dict[str, Any] | None = None, email: dict[str, Any] | None = None, funds_remaining: float, id: str, ip_address: dict[str, Any] | None = None, queries_remaining: int, risk_score: float, shipping_address: dict[str, Any] | None = None, shipping_phone: dict[str, Any] | None = None, warnings: list[dict[str, Any]] | None = None, **_: Any)¶

Bases: _Serializable

Model for Insights response.

Initialize an Insights instance.

billing_address: BillingAddress¶: A BillingAddress object containing minFraud data related to the billing address used in the transaction.

billing_phone: Phone¶: A Phone object containing minFraud data related to the billing phone used in the transaction.

credit_card: CreditCard¶: A CreditCard object containing minFraud data about the credit card used in the transaction.

device: Device¶: A Device object containing information about the device that MaxMind believes is associated with the IP address passed in the request.

disposition: Disposition¶: A Disposition object containing the disposition for the request as set by custom rules.

email: Email¶: A Email object containing information about the email address passed in the request.

funds_remaining: float¶: The approximate US dollar value of the funds remaining on your MaxMind account.

id: str¶: This is a UUID that identifies the minFraud request. Please use this ID in bug reports or support requests to MaxMind so that we can easily identify a particular request.

ip_address: IPAddress¶: A IPAddress object containing GeoIP and minFraud Insights information about the IP address.

queries_remaining: int¶: The approximate number of queries remaining on this service before your account runs out of funds.

risk_score: float¶: This property 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.

shipping_address: ShippingAddress¶: A ShippingAddress object containing minFraud data related to the shipping address used in the transaction.

shipping_phone: Phone¶: A Phone object containing minFraud data related to the shipping phone used in the transaction.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

warnings: list[ServiceWarning]¶: This list contains ServiceWarning objects detailing issues with the request that was sent such as invalid or unknown inputs. It is highly recommended that you check this list for issues when integrating the web service.

class minfraud.models.Issuer(*, name: str | None = None, matches_provided_name: bool | None = None, phone_number: str | None = None, matches_provided_phone_number: bool | None = None, **_: Any)¶

Bases: _Serializable

Information about the credit card issuer.

Initialize an Issuer instance.

matches_provided_name: bool | None¶: This property 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 property is None if either no name or no issuer ID number (IIN) was provided in the request or if MaxMind does not have a name associated with the IIN.

matches_provided_phone_number: bool | None¶: This property 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. It is None if either no phone number or no issuer ID number (IIN) was provided in the request or if MaxMind does not have a phone number associated with the IIN.

name: str | None¶: The name of the bank which issued the credit card.

phone_number: str | None¶: The phone number of the bank which issued the credit card. In some cases the phone number we return may be out of date.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

Bases: _Serializable

Information about the billing or shipping phone number.

Initialize a Phone instance.

country: str | None¶: The two-character ISO 3166-1 country code for the country associated with the phone number.

is_voip: bool | None¶: This property is True if the phone number is a Voice over Internet Protocol (VoIP) number allocated by a regulator. The property is False when the number is not VoIP. If the phone number was not provided or we do not have data for it, the property will be None.

matches_postal: bool | None¶: This is `True` if the phone number’s prefix is commonly associated with the postal code. It is `False` if the prefix is not associated with the postal code. It is non-`None` only when the phone number is in the US, the number prefix is in our database, and the postal code and country are provided in the request.

network_operator: str | None¶: The name of the original network operator associated with the phone number. This field does not reflect phone numbers that have been ported from the original operator to another, nor does it identify mobile virtual network operators.

number_type: str | None¶: One of the following values: fixed or mobile. Additional values may be added in the future.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

class minfraud.models.Reason(*, code: str | None = None, reason: str | None = None, **_: Any)¶

Bases: _Serializable

The risk score reason for the multiplier.

This class provides both a machine-readable code and a human-readable explanation of the reason for the risk score.

See the risk reasons documentation for the current list of reason codes.

Initialize a Reason instance.

code: str | None¶

This value is a machine-readable code identifying the reason.

Although more codes may be added in the future, the current codes are:

BROWSER_LANGUAGE - Riskiness of the browser user-agent and language associated with the request.
BUSINESS_ACTIVITY - Riskiness of business activity
associated with the request.
COUNTRY - Riskiness of the country associated with the request.
CUSTOMER_ID - Riskiness of a customer’s activity.
EMAIL_DOMAIN - Riskiness of email domain.
EMAIL_DOMAIN_NEW - Riskiness of newly-sighted email domain.
EMAIL_ADDRESS_NEW - Riskiness of newly-sighted email address.
EMAIL_LOCAL_PART - Riskiness of the local part of the email address.
EMAIL_VELOCITY - Velocity on email - many requests on same email over short period of time.
ISSUER_ID_NUMBER_COUNTRY_MISMATCH - Riskiness of the country mismatch between IP, billing, shipping and IIN country.
ISSUER_ID_NUMBER_ON_SHOP_ID - Risk of Issuer ID Number for the shop ID.
ISSUER_ID_NUMBER_LAST_DIGITS_ACTIVITY - Riskiness of many recent requests and previous high-risk requests on the IIN and last digits of the credit card.
ISSUER_ID_NUMBER_SHOP_ID_VELOCITY - Risk of recent Issuer ID Number activity for the shop ID.
INTRACOUNTRY_DISTANCE - Risk of distance between IP, billing, and shipping location.
ANONYMOUS_IP - Risk due to IP being an Anonymous IP.
IP_BILLING_POSTAL_VELOCITY - Velocity of distinct billing postal code on IP address.
IP_EMAIL_VELOCITY - Velocity of distinct email address on IP address.
IP_HIGH_RISK_DEVICE - High-risk device sighted on IP address.
IP_ISSUER_ID_NUMBER_VELOCITY - Velocity of distinct IIN on IP address.
IP_ACTIVITY - Riskiness of IP based on minFraud network activity.
LANGUAGE - Riskiness of browser language.
MAX_RECENT_EMAIL - Riskiness of email address based on past minFraud risk scores on email.
MAX_RECENT_PHONE - Riskiness of phone number based on past minFraud risk scores on phone.
MAX_RECENT_SHIP - Riskiness of email address based on past minFraud risk scores on ship address.
MULTIPLE_CUSTOMER_ID_ON_EMAIL - Riskiness of email address having many customer IDs.
ORDER_AMOUNT - Riskiness of the order amount.
ORG_DISTANCE_RISK - Risk of ISP and distance between billing address and IP location.
PHONE - Riskiness of the phone number or related numbers.
CART - Riskiness of shopping cart contents.
TIME_OF_DAY - Risk due to local time of day.
TRANSACTION_REPORT_EMAIL - Risk due to transaction reports on the email address.
TRANSACTION_REPORT_IP - Risk due to transaction reports on the IP address.
TRANSACTION_REPORT_PHONE - Risk due to transaction reports
on the phone number.
TRANSACTION_REPORT_SHIP - Risk due to transaction reports
on the shipping address.
EMAIL_ACTIVITY - Riskiness of the email address based on minFraud network activity.
PHONE_ACTIVITY - Riskiness of the phone number
based on minFraud network activity.
SHIP_ACTIVITY - Riskiness of ship address based on minFraud network activity.

reason: str | None¶: This property provides a human-readable explanation of the reason. The text may change at any time and should not be matched against.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

class minfraud.models.RiskScoreReason(*, multiplier: float, reasons: list[dict[str, Any]] | None = None, **_: Any)¶

Bases: _Serializable

The risk score multiplier and the reasons for that multiplier.

Initialize a RiskScoreReason instance.

multiplier: float¶: The factor by which the risk score is increased (if the value is greater than 1) or decreased (if the value is less than 1) for given risk reason(s). Multipliers greater than 1.5 and less than 0.66 are considered significant and lead to risk reason(s) being present.

reasons: list[Reason]¶: This list contains Reason objects that describe one of the reasons for the multiplier.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

class minfraud.models.Score(*, disposition: dict[str, Any] | None = None, funds_remaining: float, id: str, ip_address: dict[str, Any] | None = None, queries_remaining: int, risk_score: float, warnings: list[dict[str, Any]] | None = None, **_: Any)¶

Bases: _Serializable

Model for Score response.

Initialize a Score instance.

disposition: Disposition¶: A Disposition object containing the disposition for the request as set by custom rules.

funds_remaining: float¶: The approximate US dollar value of the funds remaining on your MaxMind account.

id: str¶: This is a UUID that identifies the minFraud request. Please use this ID in bug reports or support requests to MaxMind so that we can easily identify a particular request.

ip_address: ScoreIPAddress¶: A ScoreIPAddress object containing IP address risk.

queries_remaining: int¶: The approximate number of queries remaining on this service before your account runs out of funds.

risk_score: float¶: This property 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.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

warnings: list[ServiceWarning]¶: This list contains ServiceWarning objects detailing issues with the request that was sent such as invalid or unknown inputs. It is highly recommended that you check this list for issues when integrating the web service.

class minfraud.models.ScoreIPAddress(*, risk: float | None = None, **_: Any)¶

Bases: _Serializable

Information about the IP address for minFraud Score.

Initialize a ScoreIPAddress instance.

risk: float | None¶: 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.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

class minfraud.models.ServiceWarning(*, code: str | None = None, warning: str | None = None, input_pointer: str | None = None, **_: Any)¶

Bases: _Serializable

Warning from the web service.

Initialize a ServiceWarning instance.

code: str | None¶: This value is a machine-readable code identifying the warning. See the response warnings documentation for the current list of of warning codes.

input_pointer: str | None¶: This is a string representing the path to the input that the warning is associated with. For instance, if the warning was about the billing city, the string would be "/billing/city".

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

warning: str | None¶: This property provides a human-readable explanation of the warning. The description may change at any time and should not be matched against.

Bases: _Serializable

Information about the shipping address.

Initialize a ShippingAddress instance.

distance_to_billing_address: int | None¶: The distance in kilometers from the shipping address to billing address.

distance_to_ip_location: int | None¶: The distance in kilometers from the address to the IP location.

is_high_risk: bool | None¶: This property is True if the shipping address is high risk. If the address could not be parsed or was not provided, the property is None.

is_in_ip_country: bool | None¶: This property is True if the address is in the IP country. The property is False when the address is not in the IP country. If the address could not be parsed or was not provided or if the IP address could not be geolocated, the property will be None.

is_postal_in_city: bool | None¶: This property is True if the postal code provided with the address is in the city for the address. The property is False when the postal code is not in the city. If the address was not provided, could not be parsed, or was not in USA, the property will be None.

latitude: float | None¶: The latitude associated with the address.

longitude: float | None¶: The longitude associated with the address.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

Bases: _Serializable

Risk factor scores used in calculating the overall risk score.

Deprecated since version 2.12.0: Use RiskScoreReason instead.

Initialize a Subscores instance.

avs_result: float | None¶: The risk associated with the AVS result. If present, this is a value in the range 0.01 to 99.

billing_address: float | None¶: 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: float | None¶: 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: float | None¶: 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: float | None¶: Individualized risk of chargeback for the given IP address given for your account and any shop ID passed. 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: float | None¶: 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: float | None¶: 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: float | None¶: The risk associated with the CVV result. If present, this is a value in the range 0.01 to 99.

device: float | None¶: The risk associated with the device. If present, this is a value in the range 0.01 to 99.

email_address: float | None¶: The risk associated with the particular email address. If present, this is a value in the range 0.01 to 99.

email_domain: float | None¶: The general risk associated with the email domain. If present, this is a value in the range 0.01 to 99.

email_local_part: float | None¶: The risk associated with the email address local part (the part of the email address before the @ symbol). If present, this is a value in the range 0.01 to 99.

email_tenure: float | None¶: 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.

Deprecated since version 1.8.0: Deprecated effective August 29, 2019. This risk factor score will default to 1 and will be removed in a future release. The user tenure on email is reflected in the email address risk factor score.

See also

minfraud.models.Subscores.email_address

ip_tenure: float | None¶: 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.

Deprecated since version 1.8.0: Deprecated effective August 29, 2019. This risk factor score will default to 1 and will be removed in a future release. The IP tenure is reflected in the overall risk score.

See also

minfraud.models.Score.risk_score

issuer_id_number: float | None¶: 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: float | None¶: 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: float | None¶: The risk associated with the particular phone number. If present, this is a value in the range 0.01 to 99.

shipping_address: float | None¶: The risk associated with the shipping address. If present, this is a value in the range 0.01 to 99.

shipping_address_distance_to_ip_location: float | None¶: 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: float | None¶: 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.

to_dict() → dict[str, Any]¶: Return a dict of the object suitable for serialization.

Errors¶

Typed errors thrown by this library.

exception minfraud.errors.AuthenticationError¶

Bases: MinFraudError

There was a problem authenticating the request.

add_note(object, /)¶: Exception.add_note(note) – add a note to the exception

with_traceback(object, /)¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception minfraud.errors.HTTPError(message: str, http_status: int | None = None, uri: str | None = None, decoded_content: str | None = None)¶

Bases: MinFraudError

There was an error when making your HTTP request.

This class represents an HTTP transport error. It extends MinFraudError and adds attributes of its own.

Initialize an HTTPError instance.

add_note(object, /)¶: Exception.add_note(note) – add a note to the exception

decoded_content: str | None¶: The decoded response content

http_status: int | None¶: The HTTP status code returned

uri: str | None¶: The URI queried

with_traceback(object, /)¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception minfraud.errors.InsufficientFundsError¶

Bases: MinFraudError

Your account is out of funds for the service queried.

add_note(object, /)¶: Exception.add_note(note) – add a note to the exception

with_traceback(object, /)¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception minfraud.errors.InvalidRequestError¶

Bases: MinFraudError

The request was invalid.

add_note(object, /)¶: Exception.add_note(note) – add a note to the exception

with_traceback(object, /)¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception minfraud.errors.MinFraudError¶

Bases: RuntimeError

There was a non-specific error in minFraud.

This class represents a generic error. It extends RuntimeError and does not add any additional attributes.

add_note(object, /)¶: Exception.add_note(note) – add a note to the exception

with_traceback(object, /)¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception minfraud.errors.PermissionRequiredError¶

Bases: MinFraudError

Your account does not have permission to access this service.

add_note(object, /)¶: Exception.add_note(note) – add a note to the exception

with_traceback(object, /)¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Indices and tables¶

license:: Apache License, Version 2.0

minFraud Python API¶

Description¶

Installation¶

Documentation¶

Usage¶

Score, Insights and Factors Usage¶

Report Transactions Usage¶

Request Validation (for all request methods)¶

Errors¶

Examples¶

Score, Insights and Factors Example¶

Report Transactions Example¶

Versioning¶

Support¶

Copyright and License¶

Web Service Client¶

Response Models¶

Errors¶

Indices and tables¶

Table of Contents

This Page