minFraud Score, Insights, Factors and Report Transaction Python API — minfraud 1.13.0 documentation

# minFraud Score, Insights, Factors and Report Transaction 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 use pip, you may also use easy_install from the source directory:

    $ easy_install .

## Documentation

Complete API documentation is available on Read the Docs.

## Usage

To use this API, create a new `minfraud.Client` object. The constructor takes your MaxMind account ID and license key:

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

### Score, Insights and Factors Usage

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

    >>> factors = client.factors({'device': {'ip_address': '81.2.69.160'}})

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

    >>> insights = client.insights({'device': {'ip_address': '81.2.69.160'}})

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

    >>> score = client.score({'device': {'ip_address': '81.2.69.160'}})

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. The `ip_address` in the `device` sub-dictionary is required. All other 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': '81.2.69.160', '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 `ip_address` and `tag` fields are required. All other fields are optional.

### 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 missing or 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

    >>> from minfraud import Client
    >>>
    >>> client = Client(42, 'licensekey')
    >>>
    >>> request = {
    >>>     'device': {
    >>>         'ip_address': '81.2.69.160',
    >>>         'accept_language': 'en-US,en;q=0.8',
    >>>         'session_age': 3600,
    >>>         'session_id': 'a333a4e127f880d8820e56a66f40717c',
    >>>         'user_agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36'
    >>>     },
    >>>     'event': {
    >>>         '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': '323-123-4321',
    >>>     },
    >>>     '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': '403-321-2323',
    >>>         'delivery_speed': 'same_day',
    >>>     },
    >>>     'credit_card': {
    >>>         'bank_phone_country_code': '1',
    >>>         'avs_result': 'Y',
    >>>         'bank_phone_number': '800-342-1232',
    >>>         'last_4_digits': '7643',
    >>>         'cvv_result': 'N',
    >>>         'bank_name': 'Bank of No Hope',
    >>>         'issuer_id_number': '323132'
    >>>     },
    >>>     'payment': {
    >>>         'decline_code': 'invalid number',
    >>>         'was_authorized': False,
    >>>         '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
    >>>      },
    >>>     'custom_inputs': {
    >>>         'section': 'news',
    >>>         'num_of_previous_purchases': 19,
    >>>         'discount': 3.2,
    >>>         'previous_user': True
    >>>     }
    >>> }
    >>>
    >>> client.score(request)
    Score(...)
    >>>
    >>> client.insights(request)
    Insights(...)
    >>>
    >>> client.factors(request)
    Factors(...)

### Report Transactions Example

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

## Requirements

This code requires Python 2.7+ or 3.5+. Older versions are not supported. This library has been tested with CPython and PyPy.

## 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 software is Copyright © 2015-2020 by MaxMind, Inc.

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

# Modules

## minfraud

A client API to MaxMind’s minFraud Score and Insights web services.

## minfraud.webservice

This module contains the webservice client class.

class `minfraud.webservice.` `Client`(account_id=None, license_key=None, host='minfraud.maxmind.com', locales='en', timeout=None, user_id=None)

  Client for accessing the minFraud Score and Insights web services.

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

    - locales (tuple[str]) – A tuple of locale codes to use in name property

    - timeout (float) – The timeout to use for the request.

  Returns

    Client object

  Return type

    Client

  `factors`(transaction, validate=True)

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

    Returns

      A Factors model object

    Return type

      Factors

    Raises

      AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

  `insights`(transaction, validate=True)

    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.

    Returns

      An Insights model object

    Return type

      Insights

    Raises

      AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

  `report`(report, validate=True)

    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, validate=True)

    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.

    Returns

      A Score model object

    Return type

      Score

    Raises

      AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,

## minfraud.models

This module contains models for the minFraud response object.

class `minfraud.models.` `BillingAddress`(*args, **kwargs)

  Information about the billing address.

  `distance_to_ip_location`

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

    Type

      int | None

  `is_in_ip_country`

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

    Type

      bool | None

  `is_postal_in_city`

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

    Type

      bool | None

  `latitude`

    The latitude associated with the address.

    Type

      float | None

  `longitude`

    The longitude associated with the address.

    Type

      float | None

  Create new instance.

class `minfraud.models.` `CreditCard`(*args, **kwargs)

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

  `country`

    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.

    Type

      str | None

  `brand`

    The card brand, such as “Visa”, “Discover”, “American Express”, etc.

    Type

      str | None

  `is_business`

    This property is `True` if the card is a business card.

    Type

      bool | None

  `is_issued_in_billing_address_country`

    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.

    Type

      bool | None

  `is_prepaid`

    This property is `True` if the card is a prepaid card.

    Type

      bool | None

  `is_virtual`

    This property is `True` if the card is a virtual card.

    Type

      bool | None

  `type`

    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.

    Type

      str | None

  `issuer`

    An object containing information about the credit card issuer.

    Type

      Issuer

  Create new instance.

class `minfraud.models.` `Device`(*args, **kwargs)

  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.

  `confidence`

    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.

    Type

      float | None

  `id`

    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.

    Type

      str | None

  `last_seen`

    This is the date and time of the last sighting of the device. This is an RFC 3339 date-time.

    Type

      str | None

  `local_time`

    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.

    Type

      str | None

  Create new instance.

class `minfraud.models.` `Disposition`(*args, **kwargs)

  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.

  `action`

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

    Type

      str | None

  `reason`

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

    Type

      str | None

  Create new instance.

class `minfraud.models.` `Email`(*args, **kwargs)

  Information about the email address passed in the request.

  `domain`

    An object containing information about the email domain.

    Type

      EmailDomain

  `first_seen`

    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.

    Type

      str

  `is_disposable`

    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.

    Type

      bool | None

  `is_free`

    This field is true if MaxMind believes that this email is hosted by a free email provider such as Gmail or Yahoo! Mail.

    Type

      bool | None

  `is_high_risk`

    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.

    Type

      bool | None

  Create new instance.

class `minfraud.models.` `EmailDomain`(*args, **kwargs)

  Information about the email domain passed in the request.

  `first_seen`

    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.

    Type

      str

  Create new instance.

class `minfraud.models.` `Factors`(*args, **kwargs)

  Model for Factors response.

  `id`

    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.

    Type

      str

  `funds_remaining`

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

    Type

      float

  `queries_remaining`

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

    Type

      int

  `warnings`

    This tuple 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 array for issues when integrating the web service.

    Type

      tuple[ServiceWarning]

  `risk_score`

    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.

    Type

      float

  `credit_card`

    A `CreditCard` object containing minFraud data about the credit card used in the transaction.

    Type

      CreditCard

  `device`

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

    Type

      Device

  `disposition`

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

    Type

      Disposition

  `email`

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

    Type

      Email

  `ip_address`

    A `IPAddress` object containing GeoIP2 and minFraud Insights information about the IP address.

    Type

      IPAddress

  `billing_address`

    A `BillingAddress` object containing minFraud data related to the billing address used in the transaction.

    Type

      BillingAddress

  `shipping_address`

    A `ShippingAddress` object containing minFraud data related to the shipping address used in the transaction.

  `subscores`

    A `Subscores` object containing subscores for many of the individual components that are used to calculate the overall risk score.

  Create new instance.

class `minfraud.models.` `GeoIP2Country`(*args, **kwargs)

  Country information for the IP address.

  In addition to the attributes provided by `geoip2.records.Country`, this class provides:

  `is_high_risk`

    This is true if the IP country is high risk.

    Type

      bool | None

    Deprecated since version 1.8.0: Deprecated effective August 29, 2019.

  Parent:

  Contains data for the country record associated with an IP address.

  This class contains the country-level data associated with an IP address.

  Attributes:

  `confidence`

    A value from 0-100 indicating MaxMind’s confidence that the country is correct. This attribute is only available from the Insights end point and the GeoIP2 Enterprise database.

    Type

      int

  `geoname_id`

    The GeoName ID for the country.

    Type

      int

  `is_in_european_union`

    This is true if the country is a member state of the European Union.

    Type

      bool

  `iso_code`

    The two-character ISO 3166-1 alpha code for the country.

    Type

      unicode

  `name`

    The name of the country based on the locales list passed to the constructor.

    Type

      unicode

  `names`

    A dictionary where the keys are locale codes and the values are names.

    Type

      dict

class `minfraud.models.` `GeoIP2Location`(*args, **kwargs)

  Location information for the IP address.

  In addition to the attributes provided by `geoip2.records.Location`, this class provides:

  `local_time`

    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.

    Type

      str | None

  Parent:

  Contains data for the location record associated with an IP address.

  This class contains the location data associated with an IP address.

  This record is returned by `city`, `enterprise`, and `insights`.

  Attributes:

  `average_income`

    The average income in US dollars associated with the requested IP address. This attribute is only available from the Insights end point.

    Type

      int

  `accuracy_radius`

    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.

    Type

      int

  `latitude`

    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.

    Type

      float

  `longitude`

    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.

    Type

      float

  `metro_code`

    The metro code of the location if the location is in the US. MaxMind returns the same metro codes as the Google AdWords API.

    Type

      int

    `population_density`

    The estimated population per square kilometer associated with the IP address. This attribute is only available from the Insights end point.

    Type

      int

  `time_zone`

    The time zone associated with location, as specified by the IANA Time Zone Database, e.g., “America/New_York”.

    Type

      unicode

class `minfraud.models.` `IPAddress`(ip_address)

  Model for minFraud and GeoIP2 data about the IP address.

  `risk`

    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.

    Type

      float | None

  `city`

    City object for the requested IP address.

    Type

      `geoip2.records.City`

  `continent`

    Continent object for the requested IP address.

    Type

      `geoip2.records.Continent`

  `country`

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

    Type

      `GeoIP2Country`

  `location`

    Location object for the requested IP address.

    Type

      `GeoIP2Location`

  `maxmind`

    Information related to your MaxMind account.

    Type

      `geoip2.records.MaxMind`

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

    Type

      `geoip2.records.Country`

  `represented_country`

    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.

    Type

      `geoip2.records.RepresentedCountry`

  `subdivisions`

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

    Type

      `geoip2.records.Subdivisions`

  `traits`

    Object with the traits of the requested IP address.

class `minfraud.models.` `Insights`(*args, **kwargs)

  Model for Insights response.

  `id`

    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.

    Type

      str

  `funds_remaining`

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

    Type

      float

  `queries_remaining`

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

    Type

      int

  `warnings`

    This tuple 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 array for issues when integrating the web service.

    Type

      tuple[ServiceWarning]

  `risk_score`

    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.

    Type

      float

  `credit_card`

    A `CreditCard` object containing minFraud data about the credit card used in the transaction.

    Type

      CreditCard

  `device`

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

    Type

      Device

  `disposition`

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

    Type

      Disposition

  `email`

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

    Type

      Email

  `ip_address`

    A `IPAddress` object containing GeoIP2 and minFraud Insights information about the IP address.

    Type

      IPAddress

  `billing_address`

    A `BillingAddress` object containing minFraud data related to the billing address used in the transaction.

    Type

      BillingAddress

  `shipping_address`

    A `ShippingAddress` object containing minFraud data related to the shipping address used in the transaction.

  Create new instance.

class `minfraud.models.` `Issuer`(*args, **kwargs)

  Information about the credit card issuer.

  `name`

    The name of the bank which issued the credit card.

    Type

      str | None

  `matches_provided_name`

    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.

    Type

      bool

  `phone_number`

    The phone number of the bank which issued the credit card. In some cases the phone number we return may be out of date.

    Type

      str

  `matches_provided_phone_number`

    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.

    Type

      bool

  Create new instance.

class `minfraud.models.` `Score`(*args, **kwargs)

  Model for Score response.

  `id`

    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.

    Type

      str

  `funds_remaining`

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

    Type

      float

  `queries_remaining`

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

    Type

      int

  `warnings`

    This tuple 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 array for issues when integrating the web service.

    Type

      tuple[ServiceWarning]

  `risk_score`

    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.

    Type

      float

  `disposition`

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

    Type

      Disposition

  `ip_address`

    A `ScoreIPAddress` object containing IP address risk.

    Type

      IPAddress

  Create new instance.

class `minfraud.models.` `ScoreIPAddress`(*args, **kwargs)

  Information about the IP address for minFraud Score.

  `risk`

    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.

    Type

      float | None

  Create new instance.

class `minfraud.models.` `ServiceWarning`(*args, **kwargs)

  Warning from the web service.

  `code`

    This value is a machine-readable code identifying the warning. See the web service documentation for the current list of of warning codes.

    Type

      str

  `warning`

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

    Type

      str

  `input_pointer`

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

    Type

      str

  Create new instance.

class `minfraud.models.` `ShippingAddress`(*args, **kwargs)

  Information about the shipping address.

  `distance_to_ip_location`

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

    Type

      int | None

  `is_in_ip_country`

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

    Type

      bool | None

  `is_postal_in_city`

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

    Type

      bool | None

  `latitude`

    The latitude associated with the address.

    Type

      float | None

  `longitude`

    The longitude associated with the address.

    Type

      float | None

  `is_high_risk`

    This property is `True` if the shipping address is in the IP country. The property is `false` when the address is not in the IP country. If the shipping address could not be parsed or was not provided or the IP address could not be geolocated, then the property is `None`.

    Type

      bool | None

  `distance_to_billing_address`

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

    Type

      int | None

  Create new instance.

class `minfraud.models.` `Subscores`(*args, **kwargs)

  Subscores used in calculating the overall risk score.

  `avs_result`

    The risk associated with the AVS result. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `billing_address`

    The risk associated with the billing address. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `billing_address_distance_to_ip_location`

    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.

    Type

      float | None

  `browser`

    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.

    Type

      float | None

  `chargeback`

    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.

    Type

      float | None

  `country`

    The risk associated with the country the transaction originated from. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `country_mismatch`

    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.

    Type

      float | None

  `cvv_result`

    The risk associated with the CVV result. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `device`

    The risk associated with the device. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `email_address`

    The risk associated with the particular email address. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `email_domain`

    The general risk associated with the email domain. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `email_local_part`

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

    > type

    >   float | None

    `email_tenure`

      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.

      Type

        float | None

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

      See also

      `minfraud.models.Subscores.email_address`

  `ip_tenure`

    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.

    Type

      float | None

    Deprecated since version 1.8.0: Deprecated effective August 29, 2019. This subscore 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`

    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.

    Type

      float | None

  `order_amount`

    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.

    Type

      float | None

  `phone_number`

    The risk associated with the particular phone number. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `shipping_address`

    The risk associated with the shipping address. If present, this is a value in the range 0.01 to 99.

    Type

      float | None

  `shipping_address_distance_to_ip_location`

    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.

    Type

      float | None

  `time_of_day`

    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.

    Type

      float | None

  Create new instance.

## minfraud.errors

This module contains errors that are raised by this package.

exception `minfraud.errors.` `AuthenticationError`

  There was a problem authenticating the request.

exception `minfraud.errors.` `HTTPError`(message, http_status=None, uri=None)

  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.

  `http_status:`

    The HTTP status code returned

    Type

      int

  `uri:`

    The URI queried

    Type

      str

exception `minfraud.errors.` `InsufficientFundsError`

  Your account is out of funds for the service queried.

exception `minfraud.errors.` `InvalidRequestError`

  The request was invalid.

exception `minfraud.errors.` `MinFraudError`

  There was a non-specific error in minFraud.

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

exception `minfraud.errors.` `PermissionRequiredError`

  Your account does not have permission to access this service.

# Indices and tables

- Index

- Module Index

- Search Page

copyright

  © 2015-2020 by MaxMind, Inc.

license

  Apache License, Version 2.0