minFraud Chargeback Web Service API

Reporting chargebacks to MaxMind helps us detect about 10-50% more fraud for your company. We offer two ways to submit chargeback data, through an online form or via an API that is documented on this page.


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/chargeback.

The minfraud.maxmind.com hostname automatically picks the data center geographically closest to you. In some cases, this data center may not be the one that provides you with the best service. You can explicitly try the following hostnames to see which one provides the best performance for you:

  • minfraud-us-east.maxmind.com
  • minfraud-us-west.maxmind.com
  • minfraud-eu-west.maxmind.com


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

Name Type Description

Required Fields

The following fields are required.

ip_address string

The IP address of the customer placing the order. This should be passed as a string like “” or “2001:db8::2:1”.

Optional Fields

The following fields are optional.

chargeback_code string

A string which is provided by your payment processor indicating the reason for the chargeback.

tag string

A string indicating the likelihood that a transaction may be fraudulent. Possible values: `not_fraud`, `suspected_fraud`, `spam_or_abuse`, or `chargeback`.

This field used to be called fraud_score, which is now deprecated. In the short term, the API will accept both fraud_score and tag as valid keys. Also during this transition period, fraud_score‘s previously accepted value `known_fraud` will still be accepted, but will be automatically mapped to `chargeback`.

maxmind_id string (8)

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. This field is not required, but you are encouraged to provide it, if possible.

minfraud_id string (36)

A UUID that identifies a minFraud Score, minFraud Insights, or minFraud Factors request. This ID is returned at /id in the response. This field is not required, but you are encouraged to provide it if the request was made to one of these services.

transaction_id string

The transaction ID you originally passed to minFraud. This field is not required, but you are encouraged to provide it or the transaction’s maxmind_id or minfraud_id.

Request Headers

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


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.

Code HTTP Status Description

Error Codes


Possible values for fraud_score are ‘not_fraud’, ‘suspected_fraud’ and ‘known_fraud’. Supplying any other value for fraud_score will trigger this error.

JSON_INVALID 400 Bad Request

Your JSON could not be parsed.


You 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.


You 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.


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.


You have not supplied a valid IPv4 or IPv6 address.


You have not supplied an IP address, which is a required field.


You have supplied an IP address which belongs to a reserved or private range.


You have supplied an invalid MaxMind account ID and/or license key in the Authorization header.


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 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 Available

There is a problem with the web service server. You can try this request again later.

Client Code Examples


#!/usr/bin/env perl

use strict;
use warnings;

use Getopt::Long;
use JSON::XS qw( decode_json encode_json );
use HTTP::Request;
use LWP::UserAgent;
use MIME::Base64 qw( encode_base64);
use Try::Tiny;

my $account_id  = 1;
my $license_key = 'foo';
my $url         = 'https://minfraud.maxmind.com/minfraud/chargeback';

# usage:
# perl chargeback-ws.pl --chargeback_code foo --fraud_score suspected_fraud --ip_address --maxmind_id 1234567890 --transaction_id 123bar

my %opt = (
    chargeback_code => undef,
    fraud_score     => undef,
    ip_address      => undef,
    maxmind_id      => undef,
    transaction_id  => undef,

    'chargeback_code:s' => \$opt{chargeback_code},
    'fraud_score:s'     => \$opt{fraud_score},
    'ip_address:s'      => \$opt{ip_address},
    'maxmind_id:s'      => \$opt{maxmind_id},
    'transaction_id:s'  => \$opt{transaction_id},

my $auth = encode_base64( $account_id . ':' . $license_key );
my $ua   = LWP::UserAgent->new(
    agent             => 'ChargeBackPoster/1.0',
    keep_alive        => 10,
    protocols_allowed => ['https'],

my %content = %opt;
delete $content{$_} for grep { !$content{$_} } keys %content;

my $req = HTTP::Request->new( 'POST', $url, undef, encode_json( \%content ) );

$req->header( 'Content-Type'  => 'application/json' );
$req->header( 'Authorization' => "Basic $auth" );

my $response = $ua->request($req);

if ( !$response->is_success ) {
    try {
        my $msg = decode_json( $response->content );
        printf( "\nError: %s (%s)\n\n", $msg->{error}, $msg->{code} );
    catch {
        printf( "Error: %s, (%s", $response->code, $response->content );

print "Chargeback posted successfully\n";


curl -H "Content-Type: application/json"                \
     --user 1:foo                                       \
     -XPOST                                             \
     -v                                                 \
     -d '{"ip_address":"","transaction_id":"1"}' \