Reporting transactions as chargebacks, suspected fraud, spam/abuse, and/or false positive (not fraud) to MaxMind helps us detect about 10-50% more fraud and reduce false positives for you.
You can report a transaction manually through the account portal’s web form or your minFraud Transactions page. This guide will show you how to programmatically report a transaction using our official client libraries.
MaxMind offers and highly recommends using official client libraries to access the Report Transation API. If you cannot or do not wish to use our client libraries, please review our minFraud Report Transaction API Documentation for details on our JSON API.
We have a collection of officially supported libraries for you to interact with the minFraud API:
A transaction report only needs two things, the IP address of the customer that placed the order and a "tag". A "tag" can be one of the following values:
|Chargeback||Used to associate a chargeback with a transaction|
|Not fraud||Used to report a transaction that was later identified as a false positive|
|Spam or Abuse||Used to report a transaction that was linked to spam or abuse|
|Suspected fraud||Used to report a high risk transaction where fraud has not yet been confirmed|
We highly encourage you to include the MaxMind ID or minFraud ID that identifies the minFraud Standard/Premium request or minFraud Score/Insights/Factors request respectively. Alternatively, you can send us the transaction ID you originally passed to the minFraud service.
The transaction report object may optionally contain a chargeback code and notes about the transaction you would like to share with MaxMind. MaxMind manually reviews many reported transactions, so any additional details you provide to help us understand context are extremely helpful.
By default, our client libaries will throw an exception if any of the transaction report object's values are invalid. The exception is thrown when the object is constructed; the python library will raise an error when the minFraud service method is called.
If the report transaction request fails, our client libraires will throw an exception, raise an error (python), or reject the promise (node).
For more information on errors and exceptions, including their types and descriptions, go to the specific library's documentation page.
The HTTP API requires you to pass a set of parameters as JSON via an HTTP POST.
The URI for this service is
minfraud.maxmind.com hostname automatically picks the data center
geographically closest to you.
Content-Type header should always be
The minFraud API accepts input as JSON in the body of an HTTP POST. The JSON document should consist of a single object. That object may contain the following keys (key names are case-sensitive):
|ip_address||string||Required. The IP address of the customer placing the order. This should be passed as a string like “22.214.171.124” or “2001:db8::2:1”.|
|tag||string||Required. A string indicating the likelihood that a transaction may be fraudulent. Possible values: |
|chargeback_code||string||Optional. A string which is provided by your payment processor indicating the reason for the chargeback.|
|maxmind_id||string (8)||Optional. A unique eight character string identifying a minFraud Standard or Premium request. These IDs are returned in the |
|minfraud_id||string (36)||Optional. A UUID that identifies a minFraud Score, minFraud Insights, or minFraud Factors request. This ID is returned at |
|notes||string||Optional. Your notes on the fraud tag associated with the transaction. We manually review many reported transactions to improve our scoring for you so any additional details to help us understand context are helpful.|
|transaction_id||string||Optional. The transaction ID you originally passed to minFraud. This field is not required, but you are encouraged to provide it or the transaction’s |
HTTP status codes are used to relay success and error messages. A successful POST will return a 204 (No Content) status code.
When the server returns an error (4xx or 5xx), the response may include a JSON
document in the body. This document is a single object with the keys
code field is a static error code for machine use. The value of
any given code will never change, though codes can be added or removed. The
error field is a human-readable description of the error and may change at any
Not all errors include a JSON body. An error in content negotiation will not
include a body, nor will many 5xx errors, which typically happen outside of our
web service request handling code. You should check the
Content-Type type of
an error response before attempting to decode the body as JSON.
In addition to the errors documented below, client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.
|Error Code||HTTP Status||Description|
|JSON_INVALID||400 Bad Request||Your JSON could not be parsed.|
|MAXMIND_ID_INVALID||400 Bad Request||You have supplied an invalid |
|MINFRAUD_ID_INVALID||400 Bad Request||You have supplied an invalid |
|PARAMETER_UNKNOWN||400 Bad Request||You have supplied an unknown parameter. Check the keys in your JSON data to ensure that you have not misspelled any of the field names or passed a field name which is not listed in the available input fields.|
|TAG_REQUIRED||400 Bad Request||Your request does not include a |
|TAG_INVALID||400 Bad Request||Your request includes an invalid |
|IP_ADDRESS_INVALID||400 Bad Request||You have not supplied a valid IPv4 or IPv6 address.|
|IP_ADDRESS_REQUIRED||400 Bad Request||You have not supplied an IP address, which is a required field.|
|IP_ADDRESS_RESERVED||400 Bad Request||You have supplied an IP address which belongs to a reserved or private range.|
|AUTHORIZATION_INVALID||401 Unauthorized||You have supplied an invalid MaxMind account ID and/or license key in the Authorization header.|
|LICENSE_KEY_REQUIRED||401 Unauthorized||You have not supplied a MaxMind license key in the Authorization header.|
|ACCOUNT_ID_REQUIRED||401 Unauthorized||You have not supplied a MaxMind account ID in the Authorization header.|
|(none)||415 Unsupported Media Type||Your request included a |
|(none)||503 Service Not Available||There is a problem with the web service server. You can try this request again later.|
This page was last updated on September 27, 2023.