Working with Transaction Dispositions

With minFraud Interactive, customers can create Custom Rules that are used to assign a disposition to every transaction received in a minFraud request. Custom Rules can set a transaction’s disposition to accept, reject, or manual_review. For more information on Custom Rules and Dispositions, see the documentation on our knowledge base.

After transactions are received, customers can use the account portal to review all transactions dispositioned as manual_review. Transactions can then either be accepted or rejected, and/or have a note added. Learn how to use the account portal to do manual review on our knowledge base.. In order for these manual updates made in the account portal to be useful, they need to find their way back into customers’ systems. The Dispositions API allows customers to get a list of the manual updates and notes made to their transactions.

You only need to implement the Dispositions API if you (1) use the account portal to make manual changes to dispositions, and (2) require those changes to propagate to your own system.

Making a disposition request

To make a disposition request, you need the request URI and parameters, and your MaxMind account ID and license key.

Request URI and parameters

API calls should be made with HTTP GET request to https://minfraud.maxmind.com/minfraud/disposition/v1.0/updates.

We require a URL parameter called updates_after with an RFC 3339 timestamp value. This value is an exclusive lower bound for the updates; only updates made after this time will be returned.

For example, to get updates after March 15, 2021 at 9 AM UTC, your request would look like: https://minfraud.maxmind.com/minfraud/disposition/v1.0/updates?updates_after=2021-03-15T09:00:00.00000Z

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. The authorization realm is minfraud.

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.

Request headers

The Accept header for a request is entirely optional. If you do include one, you must accept one of the following:

• application/json
• application/vnd.maxmind.com-disposition-updates+json
• application/vnd.maxmind.com-disposition-updates+json; charset=UTF-8; version=1.0

If you set the Accept-Charset header in your client code, you must accept the UTF-8 character set. If you don’t you will receive a 406 Not Acceptable response.

Command Line Example Using curl

This example will get updates after March 15, 2021 at 9AM UTC. Please replace {account_id} and {license_key} with your account ID and license key

1curl -u "{account_id}:{license_key}" \
2  https://minfraud.maxmind.com/minfraud/disposition/v1.0/updates\?updates_after\=2021-03-15T09:00:00.00000Z

Response to successful requests

Headers (successful)

The Content-Type header for a successful response is application/vnd.maxmind.com-disposition-updates+json; charset=UTF-8; version=1.0.

A Content-Length header will be provided.

Body (successful)

Data will be returned as a JSON document in UTF-8 encoding. The document will include two keys: last_update_timestamp and updates.

The last_update_timestamp value provides the relevant timestamp the last returned transaction was sorted by, in RFC 3339 format (NB: this value is not necessarily the earlier of the *_last_updated keys of the last included transaction; this is why it’s being provided explicitly).

The updates value provides an array of transactions for which the disposition and/or note have been manually updated, or, the transaction’s manual review period has expired. The transactions will be sorted from least recently updated to most recently updated, using the earliest updated timestamp (either the disposition or note) after the updates_after time for each transaction.

At most, 1000 updated transactions will be returned for any single request. These will be the earliest updated transactions after the provided updates_after timestamp, not the most recent. For each repeated request, the updates_after request value should be replaced with the last_update_timestamp value returned from the previous request.

Each transaction in the updates array will contain the following keys:

As a note to implementers, we are considering adding additional keys to this object in future versions of this API.

Example response to a successful request

 1{
 2  "last_update_timestamp": "2017-03-15T22:06:56.848123Z",
 3  "updates": [
 4    {
 5      "minfraud_id": "deadbeef-0000-0000-0000-00000000",
 6      "action": "accept",
 7      "action_last_updated": "2017-03-14T22:04:01.04425Z",
 8      "note": null,
 9      "note_last_updated": null
10    },
11    {
12      "minfraud_id": "deadbeef-0000-0000-0000-00000002",
13      "action": "reject",
14      "action_last_updated": "2017-03-14T21:39:57.854300Z",
15      "note": null,
16      "note_last_updated": "2017-03-15T11:37:42.83235Z"
17    },
18    {
19      "minfraud_id": "deadbeef-0000-0000-0000-00000003",
20      "action": "manual_review",
21      "action_last_updated": "2017-03-04T20:14:42.757200Z",
22      "note": null,
23      "note_last_updated": "2017-03-05T16:52:31.995250Z"
24    },
25    {
26      "minfraud_id": "deadbeef-0000-0000-0000-00000020",
27      "action": "manual_review",
28      "action_last_updated": "2017-03-15T22:04:11.044250Z",
29      "note": "Ndapanda, can you check this out?",
30      "note_last_updated": "2017-03-15T22:04:25.828250Z"
31    },
32    {
33      "minfraud_id": "deadbeef-0000-0000-0000-00000030",
34      "action": "accept",
35      "action_last_updated": "2017-03-15T22:05:42.954231Z",
36      "note": "Customer was travelling abroad.",
37      "note_last_updated": "2017-03-15T22:05:58.132423Z"
38    },
39    {
40      "minfraud_id": "deadbeef-0000-0000-0000-00000050",
41      "action": "expired_review",
42      "action_last_updated": "2017-03-15T22:06:22.492945Z",
43      "note": "Customer didn't answer several phone calls.",
44      "note_last_updated": "2017-03-15T22:06:56.848123Z"
45    }
46  ]
47}

Response to unsuccessful requests

Headers (unsuccessful)

The Content-Type header for an unsuccessful response is application/vnd.maxmind.com-error+json; charset=UTF-8; version=1.0.

A Content-Length header will be provided.

Body (unsuccessful)

In the event an error occurs (the response indicates a 4xx or 5xx HTTP status), the response may include a JSON document in the body. An error in content negotiation will not include a body, nor will many 5xx errors, which typically happen outside of our web service handling code. Before attempting to decode the body as JSON, you should verify that the Content-Type of the error response is application/vnd.maxmind.com-error+json; charset=UTF-8; version=1.0.

If the JSON document is included in the response body, it will be 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.

In addition to the errors documented below, client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.

Example response to an unsuccessful request

1{
2  "code": "ACCOUNT_ID_REQUIRED",
3  "error": "You have not supplied a MaxMind account ID in the Authorization header"
4}