minFraud Score and Insights Python API¶
Beta Note¶
This is a beta release. The API may change before the first production release.
You may find information on the changes in minFraud Score and minFraud Insights in our What’s New documentation.
Description¶
This package provides an API for the MaxMind minFraud Score and Insights web services.
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 .
Usage¶
To use this API, create a new minfraud.Client
object. The constructor
takes your MaxMind user ID and license key:
>>> client = Client(42, 'licensekey')
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:
>>> insights = client.insights({'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.
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 user ID is invalid.minfraud.InsufficientFundsError
- This will be raised when your account is out of funds.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.
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',
>>> '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
>>> }
>>> }
>>>
>>> client.score(request)
Score(credits_remaining=5077062248, id='FB49B8E0-F987-11E4-8AD9-8B1442B6BA89', risk_score=56.41, warnings=())
>>>
>>> client.insights(request)
Insights(...)
Requirements¶
This code requires Python 2.6+ or 3.3+. 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 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
(user_id, license_key, host='minfraud.maxmind.com', locales=('en', ), timeout=None)¶ Client for accessing the minFraud Score and Insights web services.
Constructor for Client.
Parameters: Returns: Client object
Return type: -
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: Raises: AuthenticationError, InsufficientFundsError, 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: Raises: AuthenticationError, InsufficientFundsError, InvalidRequestError, HTTPError, MinFraudError,
- transaction (dict) –
-
minfraud.models¶
This module contains models for the minFraud response object.
-
class
minfraud.models.
BillingAddress
¶ 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 isFalse
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 beNone
.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 isFalse
when the postal code is not in the city. If the address could not be parsed or was not provided, the property will beNone
.Type: bool | None
-
latitude
¶ The latitude associated with the address.
Type: float | None
-
longitude
¶ The longitude associated with the address.
Type: float | None
-
-
class
minfraud.models.
CreditCard
¶ Information about the credit card based on the issuer ID number
-
country
¶ This property contains an ISO 3166-1 alpha-2 country code representing the country that the card was issued in.
Type: str | None
-
is_issued_in_billing_address_country
¶ This property is true if the country of the billing address matches the country that the credit card was issued in.
Type: bool | None
-
is_prepaid
¶ This property is
True
if the card is a prepaid card.Type: bool | None
-
issuer
¶ An object containing information about the credit card issuer.
Type: Issuer
-
-
class
minfraud.models.
GeoIP2Country
(locales=None, **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
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.
Type: int
-
geoname_id
¶ The GeoName ID for the country.
Type: int
-
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
(**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 and insights.
Attributes:
-
accuracy_radius
¶ The radius in kilometers around the specified location where the IP address is likely to be. This attribute is only available from the Insights end point.
Type: int
-
latitude
¶ The latitude of the location as a floating point number.
Type: float
-
longitude
¶ The longitude of the location as a floating point number.
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
-
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
¶ 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
-
credits_remaining
¶ The approximate number of service credits remaining on your account.
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
-
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.
-
-
class
minfraud.models.
Issuer
¶ 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 isFalse
if the name does not match. The property isNone
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 isFalse
if the number does not match. It isNone
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
-
-
class
minfraud.models.
Score
¶ 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
-
credits_remaining
¶ The approximate number of service credits remaining on your account.
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
-
-
class
minfraud.models.
ServiceWarning
¶ 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
¶ This is a tuple of keys representing the path to the input that the warning is associated with. For instance, if the warning was about the billing city, the tuple would be
("billing", "city")
. The key is used for an object and the index number for an array.Type: tuple[str|int]
-
-
class
minfraud.models.
ShippingAddress
¶ 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 isFalse
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 beNone
.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 isFalse
when the postal code is not in the city. If the address could not be parsed or was not provided, the property will beNone
.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 isfalse
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 isNone
.Type: bool | None
-
distance_to_billing_address
¶ The distance in kilometers from the shipping address to billing address.
Type: int | None
-
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.
Indices and tables¶
copyright: | © 2015 by MaxMind, Inc. |
---|---|
license: | Apache License, Version 2.0 |