Ruby API for MaxMind minFraud Services


This package provides an API for the MaxMind minFraud web services. This includes minFraud Score, Insights, and Factors. It also includes our minFraud Report Transaction API.

The legacy minFraud Standard and Premium services are not supported by this API.


This gem works with Ruby 1.9 and above.


Add this line to your application's Gemfile:

gem 'minfraud'

And then execute:

$ bundle

Or install it yourself as:

$ gem install minfraud



An account ID and license key are required to work with the web services.

Minfraud.configure do |c|
  c.  = 12345
  c.license_key = 'your_license_key'

Making a minFraud Score, Insights, or Factors Request

# You can either provide a hash of parameters to the initializer
assessment =
  device: {
    ip_address: ''
# or create a component and assign them to the assessments object directly
device = '')
assessment = device)
# or
assessment =
assessment.device = device

# There are multiple components that reflect the minFraud request top level
# keys.

# Some components will raise an error if provided with the wrong values for
# attributes, e.g
event = 'foobar') # => Minfraud::NotEnumValueError

# You can check the list of permitted values for the attribute by calling a
# class method
Minfraud::Components::Event.type_values # => ["account_creation", "account_login", ....]

# You can now call 3 different minFraud endpoints: score, insights and factors

result = assessment.score # => Minfraud::Response instance

result.status  # => Response status code
result.code    # => minFraud-specific response code
result.body    # => Response body
result.headers # => Response headers

# You can change data between requests
first_request = assessment.insights
assessment.device.ip_address = ''
second_request = assessment.insights

See the API documentation for more details.

Reporting a Transaction to MaxMind

MaxMind encourages the use of this API, as data received through this channel is continually used to improve the accuracy of their fraud detection algorithms.

To use the Report Transactions API, create a new Minfraud::Components::Report::Transaction object. An IP address and a valid tag are required arguments for this API. Additional params may also be set, as documented below.

If the report is successful, nothing is returned. If the report fails, an exception with be thrown.

See the API documentation for more details.

# The report_transaction method only makes use of a transaction component:
txn =
  ip_address:     '',
  tag:            :suspected_fraud,
  maxmind_id:     '12345678',
  minfraud_id:    '58fa38d8-4b87-458b-a22b-f00eda1aa20d',
  notes:          'notes go here',
  transaction_id: '1FA254yZ'
reporter = txn)

See the API documentation for more details.


The gem supplies several distinct exception-types:

  • RequestFormatError - Raised if unpermitted key is provided to the Minfraud::Assessments initializer
  • ClientError - Raised if the IP address is absent, reserved or the JSON body cannot be decoded
  • AuthorizationError - Raised if there are problems with the account ID and/or license key
  • ServerError - Raised if minFraud returns an error or if there is an HTTP error
  • NotEnumValueError - Raised if an attribute value doesn't belong to the predefined set of values


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

If you are having an issue with the minFraud service that is not specific to the client API, please see our support page.


Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


This API uses Semantic Versioning.

Copyright (c) 2016-2020 kushnir.yb.

Copyright (c) 2020 MaxMind, Inc.

The gem is available as open source under the terms of the MIT License.

Thank You

This gem is the work of the creator and original maintainer kushnir.yb (@kushniryb).