Report a transaction

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.

Implementation

MaxMind offers and highly recommends using official client libraries to access the Report Transaction 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.

1. Install the minFraud client library

We have a collection of officially supported libraries for you to interact with the minFraud API:

1// Install via NuGet
2Install-Package MaxMind.MinFraud
 1// Install via Maven, recommended
 2<dependency>
 3  <groupId>com.maxmind.minfraud</groupId>
 4  <artifactId>minfraud</artifactId>
 5  <version>1.15.0</version>
 6</dependency>
 7
 8// Or install via Gradle
 9repositories {
10  mavenCentral()
11}
12dependencies {
13  compile 'com.maxmind.minfraud:minfraud:1.15.0'
14}
1// Install via npm
2npm install @maxmind/minfraud-api-node
3
4// Or install via yarn
5yarn add @maxmind/minfraud-api-node
1# Install via Composer
2composer require maxmind/minfraud:~1.0
1# Install via pip
2pip install minfraud
1# Install as a gem
2gem install minfraud
3
4# Or add this to your Gemfile
5gem 'minfraud'

2. Create and submit a transaction report object

A transaction report only needs two fields, a transaction identifier, which can be the ip_address, the maxmind_id, the minfraud_id, or the transaction_id, and a tag. A tag can be one of the following values:

TagDescription
ChargebackUsed to associate a chargeback with a transaction
Not fraudUsed to report a transaction that was later identified as a false positive
Spam or AbuseUsed to report a transaction that was linked to spam or abuse
Suspected fraudUsed 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.

 1var client = new WebServiceClient(10, "LICENSEKEY");
 2
 3var report = new TransactionReport(
 4    ipAddress: IPAddress.Parse("1.1.1.1"),
 5    tag: TransactionReportTag.Chargeback,
 6
 7    // The following key/values are not mandatory but are encouraged
 8    maxmindId: "abcd1234",
 9    minfraudId: new Guid("01c25cb0-f067-4e02-8ed0-a094c580f5e4"),
10    transactionId: "txn123");
11    chargebackCode: "BL",
12    notes: "Suspicious account behavior",
13
14await client.ReportAsync(report);
 1WebServiceClient client = new WebServiceClient.Builder(10, "LICENSEKEY").build();
 2
 3TransactionReport transaction = new TransactionReport.Builder(InetAddress.getByName("1.1.1.1"), Tag.Chargeback)
 4    // The following key/values are not mandatory but are encouraged
 5    .maxmindId("abcd1234")
 6    .minfraudId(UUID.fromString("01c25cb0-f067-4e02-8ed0-a094c580f5e4"))
 7    .transactionId("txn123")
 8    .chargebackCode("BL")
 9    .notes("Suspicious account behavior")
10    .build();
11
12client.reportTransaction(transaction);
 1import * as minFraud from '@maxmind/minfraud-api-node';
 2
 3const client = new minFraud.Client('10', 'LICENSEKEY');
 4
 5const transactionReport = new minFraud.TransactionReport({
 6    ipAddress: '1.1.1.1',
 7    tag: minFraud.Constants.Tag.CHARGEBACK,
 8
 9    // The following key/values are not mandatory but are encouraged
10    maxmindId: 'abcd1234',
11    minfraudId: '01c25cb0-f067-4e02-8ed0-a094c580f5e4',
12    transactionId: 'txn123',
13    chargebackCode: 'BL'
14    notes: 'Suspicious account behavior',
15  });
16
17client.reportTransaction(transactionReport).then(() => ...);
 1require_once 'vendor/autoload.php';
 2use MaxMind\MinFraud\ReportTransaction;
 3
 4$rt = new ReportTransaction(10, 'LICENSEKEY');
 5
 6$rt->report([
 7    'ip_address'      => '1.1.1.1',
 8    'tag'             => 'chargeback',
 9    // The following key/values are not mandatory but are encouraged
10    'maxmind_id'      => 'abcd1234',
11    'minfraud_id'     => '01c25cb0-f067-4e02-8ed0-a094c580f5e4',
12    'transaction_id'  => 'txn123',
13    'chargeback_code' => 'BL',
14    'notes'           => 'Suspicious account behavior',
15]);
 1from minfraud import Client
 2
 3client = Client(10, 'LICENSEKEY');
 4
 5transaction_report = {
 6  'ip_address': '1.1.1.1',
 7  'tag': 'chargeback',
 8  # The following key/values are not mandatory but are encouraged
 9  'maxmind_id': 'abcd1234'
10  'minfraud_id': '01c25cb0-f067-4e02-8ed0-a094c580f5e4',
11  'transaction_id': 'txn123',
12  'chargeback_code': 'BL',
13  'notes': 'Suspicious account behavior',
14}
15
16client.report(transaction_report)
17
18# If you want to use asynchronous requests
19import asyncio
20from minfraud import Client
21
22async_client = AsyncClient(10, 'LICENSEKEY');
23
24async def report():
25  transaction_report = {
26    'ip_address': '1.1.1.1',
27    'tag': 'chargeback',
28    # The following key/values are not mandatory but are encouraged
29    'maxmind_id': 'abcd1234'
30    'minfraud_id': '01c25cb0-f067-4e02-8ed0-a094c580f5e4',
31    'transaction_id': 'txn123',
32    'chargeback_code': 'BL',
33    'notes': 'Suspicious account behavior',
34  }
35  await async_client.report(transaction_report)
36
37asyncio.run(report())
 1Minfraud.configure do |c|
 2  c.account_id = 10
 3  c.license_key = 'LICENSEKEY'
 4end
 5
 6txn = Minfraud::Components::Report::Transaction.new(
 7  ip_address:      '1.1.1.1',
 8  tag:             :chargeback,
 9  # The following key/values are not mandatory but are encouraged
10  maxmind_id:      'abcd1234',
11  minfraud_id:     '01c25cb0-f067-4e02-8ed0-a094c580f5e4',
12  transaction_id:  'txn123'
13  chargeback_code: 'BL'
14  notes:           'Suspicious account behavior',
15)
16
17reporter = Minfraud::Report.new(transaction: txn)
18reporter.report_transaction

Validation and error handling

By default, our client libraries 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 libraries 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.

API Documentation

The HTTP API requires you to pass a set of parameters as JSON via an HTTP POST.

The URI for this service is https://minfraud.maxmind.com/minfraud/v2.0/transactions/report.

The minfraud.maxmind.com hostname automatically picks the data center geographically closest to you.

Authorization and Security

The HTTP Authorization header is required for authorization. The username is your MaxMind account ID. The password is your MaxMind license key.

You must be approved for a trial or purchase credit for use with our web services in order to receive an account ID and license key.

We use basic HTTP authentication. The APIs which require authentication are only available via HTTPS. The credentials are never transmitted unencrypted. If you attempt to access this service via HTTP, you will receive a 403 Forbidden HTTP response.

We require TLS 1.2 or greater for all requests to our servers to keep your data secure.

Request Headers

The Content-Type header should always be application/json.

Request Body

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):

NameTypeDescription
ip_addressstringConditionally required.1 The IP address of the customer placing the order. This should be passed as a string like “44.55.66.77” or “2001:db8::2:1”.
tagstringRequired. A string indicating the likelihood that a transaction may be fraudulent. Possible values: not_fraud, suspected_fraud, spam_or_abuse, or chargeback.
chargeback_codestringOptional. A string which is provided by your payment processor indicating the reason for the chargeback.
maxmind_idstring (8)Conditionally required.1 A unique eight character string identifying a minFraud Standard or Premium request. These IDs are returned in the maxmindID field of a response for a successful minFraud request.
minfraud_idstring (36)Conditionally required.1 A UUID that identifies a minFraud Score, minFraud Insights, or minFraud Factors request. This ID is returned at /id in the response.
notesstringOptional. 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_idstringConditionally required.1 The transaction ID you originally passed to minFraud.

Response

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 and error. The 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 time.

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 CodeHTTP StatusDescription
JSON_INVALID400 Bad RequestYour JSON could not be parsed.
MAXMIND_ID_INVALID400 Bad RequestYou have supplied an invalid maxmind_id. This field is case sensitive. Check your maxmind_id to ensure that it is 8 characters in length and made up only of digits and upper case letters. This value must come from the successful response to a previous minFraud request.
MINFRAUD_ID_INVALID400 Bad RequestYou have supplied an invalid minfraud_id. Check your minfraud_id to ensure that it is a valid UUID as returned in the minFraud Score, minFraud Insights, or minFraud Factors response.
PARAMETER_UNKNOWN400 Bad RequestYou 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_REQUIRED400 Bad RequestYour request does not include a tag field.
TAG_INVALID400 Bad RequestYour request includes an invalid tag field.
TRANSACTION_ID_REQUIRED400 Bad RequestYour request must include on of the following fields: ip_address, maxmind_id, minfraud_id, or transaction_id.
IP_ADDRESS_INVALID400 Bad RequestYou have not supplied a valid IPv4 or IPv6 address.
IP_ADDRESS_RESERVED400 Bad RequestYou have supplied an IP address which belongs to a reserved or private range.
AUTHORIZATION_INVALID401 UnauthorizedYou have supplied an invalid MaxMind account ID and/or license key in the Authorization header.
LICENSE_KEY_REQUIRED401 UnauthorizedYou have not supplied a MaxMind license key in the Authorization header.
ACCOUNT_ID_REQUIRED401 UnauthorizedYou have not supplied a MaxMind account ID in the Authorization header.
(none)415 Unsupported Media TypeYour request included a Content-Type header that is not supported. For GET requests, this means the web service cannot return content of that type. For PUT and POST queries, this means the web service cannot parse a request body of that type.
(none)503 Service Not AvailableThere is a problem with the web service server. You can try this request again later.

Example using curl

1curl -H "Content-Type: application/json"                \
2     --user 1:foo                                       \
3     -X POST                                            \
4     -v                                                 \
5     -d '{"ip_address":"1.2.3.4","tag":"suspected_fraud","transaction_id":"1"}' \
6     https://minfraud.maxmind.com/minfraud/v2.0/transactions/report

  1. You must provide at least one of ip_address, maxmind_id, minfraud_id, or transaction_id. You are encouraged to provide as many as you have available to help ensure your transaction is correctly matched. ↩︎ ↩︎ ↩︎ ↩︎