Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 1,490 Commits
.github		.github
dev-bin		dev-bin
src		src
.gitignore		.gitignore
.mailmap		.mailmap
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.dev.md		README.dev.md
README.md		README.md
checkstyle.xml		checkstyle.xml
pom.xml		pom.xml

Repository files navigation

MaxMind minFraud Score, Insights, and Factors Java API

Description

This package provides an API for theMaxMind minFraud Score, Insights, Factorsand Report Transaction web services.

Installation

Maven

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

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

Gradle

Add the following to yourbuild.gradle file:

repositories {    mavenCentral()}dependencies {    compile 'com.maxmind.minfraud:minfraud:4.0.0'}

API Documentation

API documentation is viewable on ourGitHubPage under the API tab.

Usage

To use this API, first create a newWebServiceClient object. The constructortakes your MaxMind account ID and license key as arguments. For example:

WebServiceClientclient =newWebServiceClient.Builder(6,"ABCD567890").build();

If you would like to use the Sandbox environment, you can use thehost methodthat belongs to the Builder. For example,

WebServiceClientclient =newWebServiceClient.Builder(6,"ABCD567890")    .host("sandbox.maxmind.com").build();

Then create a newTransaction object. This represents the transaction thatyou are sending to minFraud. The class is instantiated using an inner builderclass,Transaction.Builder. Each builder method takes a correspondingrequest model object. Each of these objects is similarly built up withcorresponding builder classes. For example:

Transactiontransaction =newTransaction.Builder(newDevice.Builder(InetAddress.getByName("1.1.1.1")).build()    ).email(newEmail.Builder()            .address("fraud@ster.com")            .build()    ).build();

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

ScoreResponsescore =client.score(transaction);

an Insights request by callinginsights method:

InsightsResponseinsights =client.insights(transaction);

a Factors request by callingfactors method:

FactorsResponsefactors =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:

TransactionReporttransaction =newTransactionReport.Builder(InetAddress.getByName("1.1.1.1"),Tag.NOT_FRAUD     ).build();client.reportTransaction(transaction);

reportTransaction() has avoid return type. If the request fails, anexception will be thrown.

See the API documentation for more details.

Exceptions

Runtime exceptions:

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

Checked exceptions:

AuthenticationException - This will be thrown when the server is unable toauthenticate the request, e.g., if the license key or account ID is invalid.
InsufficientFundsException - This will be thrown when your account is out offunds.
InvalidRequestException - This will be thrown when the server rejects therequest for another reason such as invalid JSON in the POST.
PermissionRequiredException - This will be thrown when permission isrequired to use the service.
MinFraudException - This will be thrown when the server returns anunexpected response. This also serves as the base class for the abovechecked exceptions.
HttpException -This will be thrown when an unexpected HTTP erroroccurs such as an internal server error or other unexpected status code.

Examples

Insights

Transactionrequest =newTransaction.Builder(newDevice.Builder(InetAddress.getByName("1.1.1.1"))            .acceptLanguage("en-US")            .sessionAge(3600.6)            .sessionId("foobar")            .userAgent("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.90 Safari/537.36")            .build()    ).account(newAccount.Builder()            .userId("usr-123")            .username("fraudster9")            .build()    ).billing(newBilling.Builder()            .address("11 Wall St.")            .address2("Apt 1")            .city("New Haven")            .company("Company, Inc")            .firstName("Mike")            .lastName("Smith")            .phoneCountryCode("1")            .phoneNumber("321-321-3211")            .postal("06510")            .region("CT")            .build()    ).creditCard(newCreditCard.Builder()            .avsResult('N')            .bankName("BanK of New Haven")            .bankPhoneCountryCode("1")            .bankPhoneNumber("313-231-3213")            .cvvResult('Y')            .issuerIdNumber("213312")            .lastDigits("3211")            .was3dSecureSuccessful(true)            .build()    ).email(newEmail.Builder()            .address("fraud@ster.com")            .domain("ster.com")            .build()    ).event(newEvent.Builder()            .party(Event.Party.CUSTOMER)            .shopId("2432")            .time(newDate())            .transactionId("tr1242")            .type(Event.Type.ACCOUNT_CREATION)            .build()    ).order(newOrder.Builder()            .affiliateId("af5")            .amount(newBigDecimal(Double.toString(1.1)))            .currency("USD")            .discountCode("10OFF")            .referrerUri(newURI("https://www.google.com/"))            .subaffiliateId("saf9")            .build()    ).payment(newPayment.Builder()            .declineCode("invalid")            .method(Payment.Method.CARD)            .processor(Payment.Processor.ADYEN)            .wasAuthorized(false)            .build()    ).shipping(newShipping.Builder()            .region("MN")            .postal("55455")            .phoneNumber("313-545-3113")            .phoneCountryCode("1")            .deliverySpeed(Shipping.DeliverySpeed.EXPEDITED)            .address("32 Washington Ave.")            .address2("18")            .city("Minneapolis")            .company("MinnCo")            .firstName("John")            .lastName("Doe")            .build()    ).addShoppingCartItem(newShoppingCartItem.Builder()            .category("TOYS")            .itemId("t-132")            .price(1.1)            .quantity(100)            .build()    ).addShoppingCartItem(newShoppingCartItem.Builder()            .category("COSMETICS")            .itemId("c-12312")            .price(3.)            .quantity(1)            .build()    ).customInputs(newCustomInputs.Builder()            .put("float_input",12.1)            .put("integer_input",3123)            .put("string_input","This is a string input.")            .put("boolean_input",true)            .build()    ).build();WebServiceClientclient =newWebServiceClient.Builder(6,"ABCD567890").build();System.out.println(client.insights(request));

Report Transactions API

MaxMind encourages the use of this API, as data received through this channelis continually used to improve the accuracy of our fraud detection algorithms.

To use the Report Transactions API, create a newTransactionReport object. Avalid tag at least one of the following are required arguments: IP address,MaxMind ID, minFraud ID, or transaction ID. Additional parameters may also beset, as documented below.

If the report is successful, nothing is returned. If the report fails, anexception with be thrown.

See the API documentation for more details.

TransactionReporttransaction =newTransactionReport.Builder(InetAddress.getByName("1.1.1.1"),Tag.NOT_FRAUD)    .chargebackCode("mycode")    .maxmindId("12345678")    .minfraudId(UUID.fromString("58fa38d8-4b87-458b-a22b-f00eda1aa20d"))    .notes("notes go here")    .transactionId("foo")    .build();WebServiceClientclient =newWebServiceClient.Builder(6,"ABCD567890").build();client.reportTransaction(transaction);