MaxMind minFraud Score, Insights, and Factors Java API

Description

This package provides an API for the MaxMind minFraud Score, Insights, Factors and Report Transaction web services.

Installation

Maven

We recommend installing this package with Maven. To do this, add the dependency to your pom.xml:

    <dependency>
        <groupId>com.maxmind.minfraud</groupId>
        <artifactId>minfraud</artifactId>
        <version>4.4.0</version>
    </dependency>

Gradle

Add the following to your build.gradle file:

repositories {
    mavenCentral()
}
dependencies {
    implementation 'com.maxmind.minfraud:minfraud:4.4.0'
}

API Documentation

API documentation is viewable on our GitHub Page and follow the "API documentation" link.

Usage

To use this API, first create a new WebServiceClient object. The constructor takes your MaxMind account ID and license key as arguments. For example:

WebServiceClient client = new WebServiceClient.Builder(6, "ABCD567890").build();

The WebServiceClient object is thread-safe and can be reused across requests. Reusing the object allows connection pooling and improves performance.

If you would like to use the Sandbox environment, you can use the host method that belongs to the Builder. For example:

WebServiceClient client = new WebServiceClient.Builder(6, "ABCD567890")
    .host("sandbox.maxmind.com").build();

Then create a new Transaction object. This represents the transaction that you are sending to minFraud. The class is instantiated using an inner builder class, Transaction.Builder. Each builder method takes a corresponding request model object. Each of these objects is similarly built up with corresponding builder classes. For example:

Transaction transaction = new Transaction.Builder(
        new Device.Builder(InetAddress.getByName("1.1.1.1")).build()
    ).email(
        new Email.Builder()
            .address("[email protected]")
            .build()
    ).build();

After creating the transaction object, send a Score request by calling the score method:

ScoreResponse score = client.score(transaction);

Send an Insights request by calling the insights method:

InsightsResponse insights = client.insights(transaction);

Send a Factors request by calling the factors method:

FactorsResponse factors = client.factors(transaction);

If the request succeeds, a model object will be returned for the endpoint. If the request fails, an exception will be thrown.

To report a transaction:

TransactionReport transaction = new TransactionReport.Builder(Tag.NOT_FRAUD)
    .ipAddress(InetAddress.getByName("1.1.1.1"))
    .build();
client.reportTransaction(transaction);

reportTransaction() has a void return type. If the request fails, an exception will be thrown.

See the API documentation for more details.

Connection pooling and transport retries

WebServiceClient reuses pooled HTTP connections for performance. Idle connections can be silently closed by load balancers or other intermediaries; when the next request reuses such a half-closed connection, the JDK reports the failure as a Connection reset, Broken pipe, or similar transport error.

To smooth over these intermittent failures, the SDK retries once by default. Most transport-level IOExceptions are retried; the SDK does not retry:

• Timeouts (HttpTimeoutException, including connect-phase timeouts). The SDK honors the timeouts you configure rather than extending them.
• Cancellation (InterruptedIOException, or any interrupt observed before the request runs).
• Typically deterministic failures — UnknownHostException, ConnectException, SSLHandshakeException, SSLPeerUnverifiedException. Retrying these would just delay surfacing a config bug.

HTTP 4xx and 5xx responses are surfaced through the existing exception hierarchy and are never retried. Request bodies are replayable, so retried requests are byte-identical to the original.

You can change the retry budget via the builder:

WebServiceClient client = new WebServiceClient.Builder(6, "ABCD567890")
    .maxRetries(2) // up to two retries (three total attempts)
    .build();

Set .maxRetries(0) to disable the retry entirely. Negative values throw IllegalArgumentException.

If you frequently see Connection reset errors, you can also reduce the JDK's keep-alive timeout via the system property jdk.httpclient.keepalive.timeout (in seconds) to evict pooled connections before any intermediary does so.

Exceptions

Runtime exceptions:

• IllegalArgumentException - This will be thrown when an illegal argument is passed to a builder method. For instance, a country code that is not two capital letters.

Checked exceptions:

• AuthenticationException - This will be thrown when the server is unable to authenticate the request, e.g., if the license key or account ID is invalid.
• InsufficientFundsException - This will be thrown when your account is out of funds.
• InvalidRequestException - This will be thrown when the server rejects the request for another reason such as invalid JSON in the POST.
• PermissionRequiredException - This will be thrown when permission is required to use the service.
• MinFraudException - This will be thrown when the server returns an unexpected response. This also serves as the base class for the above checked exceptions.
• HttpException - This will be thrown when an unexpected HTTP error occurs such as an internal server error or other unexpected status code.

This is the beginning of the README. Read the rest at the original. Read the full README ↗