Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 801 Commits
.github		.github
dev-bin		dev-bin
docs		docs
src/minfraud		src/minfraud
tests		tests
.gitignore		.gitignore
.readthedocs.yaml		.readthedocs.yaml
HISTORY.rst		HISTORY.rst
LICENSE		LICENSE
README.dev.rst		README.dev.rst
README.rst		README.rst
pylintrc		pylintrc
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Repository files navigation

minFraud Python API

Description

This package provides an API for theMaxMind minFraud Score, Insights, andFactors web services as well as theReport Transaction web service.

Installation

To install theminfraud module, type:

$ pip install minfraud

If you are not able to install from PyPI, you may also usepip from thesource directory:

$ python -m pip install.

Documentation

Complete API documentation is available onRead the Docs.

Usage

To use this API, create a newminfraud.Client object for a synchronousrequest orminfraud.AsyncClient for an asynchronous request. Theconstructors 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 thefactors() 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 theinsights() 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 thescore() 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 sentto the web service. The structure of this dictionary should be inthe formatspecified 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 isused to continually improve the accuracy of our fraud detection algorithms. TheReport Transaction web service is called with thereport() 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 webservice. The structure of this dictionary should be inthe format specifiedin the REST API documentation. Therequired fields aretag 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 tothe web service, the transaction dictionary structure and content will bevalidated. If validation fails, aminfraud.InvalidRequestErrorwill be raised.

If the dictionary is valid, a request will be made to the web service. If therequest 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 serveris unable to authenticate the request, e.g., if the license key or accountID is invalid.
minfraud.InvalidRequestError - This will be raised when the serverrejects the request as invalid for another reason, such as a reserved IPaddress. It is also raised if validation of the request before it is sent tothe server fails.
minfraud.HttpError - This will be raised when an unexpected HTTPerror occurs such as a firewall interfering with the request to the server.
minfraud.MinFraudError - This will be raised when some other erroroccurs such as unexpected content from the server. This also serves as thebase class for the above errors.

Additionally,score,insights andfactors may also raise:

minfraud.InsufficientFundsError - This will be raised whenyouraccount is out of funds.

Examples

Score, Insights and Factors Example

>>>import asyncio>>>from minfraudimport AsyncClient, Client>>>>>> request= {>>>'device': {>>>'ip_address':'152.216.7.110',>>>'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': {>>>'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',>>>'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>>>      },>>>'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.>>>defclient(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.>>>asyncdefasync_client(account_id,license_key):>>>asyncwith 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 minfraudimport 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 minfraudimport AsyncClient>>>>>>asyncdefreport():>>>asyncwith 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())