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.

HTTP API

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

Authorization

The HTTP Authorization header is required for authorization. The username is your MaxMind user ID. The password is your MaxMind license key. You must request a trial account or subscribe to one of our web services in order to receive a user ID and license key.

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

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 “44.55.66.77” 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.

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.

Code HTTP Status Description

Error Codes

FRAUD_SCORE_INVALID 400 Bad Request

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. Try using a tool like jsonlint.com to check your JSON for errors.

MAXMIND_ID_INVALID 400 Bad Request

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.

MINFRAUD_ID_INVALID 400 Bad 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.

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.

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

USER_ID_REQUIRED 401 Unauthorized

You have not supplied a MaxMind user 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

Perl

curl