Merge pull request #159 from maxmind/greg/ip-risk-reasons

Add suport for IP risk reasons

Author: horgh

CHANGELOG.md

@@ -9,6 +9,9 @@ CHANGELOG
   * `APS_PAYMENTS`
 * Added additional normalizing of the email address if `hashAddress` is
   enabled.
+* Added support for the IP address risk reasons in the minFraud Insights and
+  Factors responses. This is available at `response.getIpAddress().getRiskReasons()`.
+  It is a list of `IpRiskReason` objects.
 
 1.16.0 (2020-10-14)
 -------------------

README.md

@@ -77,7 +77,7 @@ an Insights request by calling `insights` method:
 InsightsResponse insights = client.insights(transaction);
 ```
 
-an Factors request by calling `factors` method:
+a Factors request by calling `factors` method:
 
 ```java
 FactorsResponse factors = client.factors(transaction);

src/main/java/com/maxmind/minfraud/response/CreditCard.java

@@ -16,8 +16,17 @@ public final class CreditCard extends AbstractModel {
     private final Boolean isVirtual;
     private final String type;
 
-    // This method is for backwards compatibility. We should remove it when we
-    // do a major release.
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param brand The credit card brand.
+     * @param country The country the card was issued in.
+     * @param isIssuedInBillingAddressCountry Whether the issuing country matches billing country.
+     * @param isPrepaid Whether the card was prepaid.
+     * @param issuer The issuer information.
+     * @param type The type.
+     */
     public CreditCard(
             String brand,
             String country,
@@ -30,8 +39,18 @@ public CreditCard(
             issuer, type);
     }
 
-    // This method is for backwards compatibility. We should remove it when we
-    // do a major release.
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param brand The credit card brand.
+     * @param country The country the card was issued in.
+     * @param isIssuedInBillingAddressCountry Whether the issuing country matches billing country.
+     * @param isPrepaid Whether the card was prepaid.
+     * @param isVirtual Whether it is a virtual card.
+     * @param issuer The issuer information.
+     * @param type The type.
+     */
     public CreditCard(
             String brand,
             String country,

src/main/java/com/maxmind/minfraud/response/Device.java

@@ -21,8 +21,14 @@ public final class Device extends AbstractModel {
     private final String lastSeen;
     private final String localTime;
 
-    // This method is for backwards compatibility. We should remove it when we
-    // do a major release.
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param confidence The device confidence.
+     * @param id The device ID.
+     * @param lastSeen When the device was last seen.
+     */
     public Device(
             Double confidence,
             UUID id,

src/main/java/com/maxmind/minfraud/response/Email.java

@@ -30,8 +30,15 @@ public Email(
         this.firstSeen = firstSeen;
     }
 
-    // The following constructors are for backward compatibility and
-    // can be removed as part of a major release
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param isDisposable Whether it is a disposable email.
+     * @param isFree Whether it is a free email.
+     * @param isHighRisk Whether it is a high risk email.
+     * @param firstSeen When the email was first seen.
+     */
     public Email(
             Boolean isDisposable,
             Boolean isFree,
@@ -41,6 +48,14 @@ public Email(
         this(null, isDisposable, isFree, isHighRisk, firstSeen);
     }
 
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param isFree Whether it is a free email.
+     * @param isHighRisk Whether it is a high risk email.
+     * @param firstSeen When the email was first seen.
+     */
     public Email(
             Boolean isFree,
             Boolean isHighRisk,
@@ -49,6 +64,13 @@ public Email(
         this(null, isFree, isHighRisk, firstSeen);
     }
 
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param isFree Whether it is a free email.
+     * @param isHighRisk Whether it is a high risk email.
+     */
     public Email(
             Boolean isFree,
             Boolean isHighRisk

src/main/java/com/maxmind/minfraud/response/GeoIp2Country.java

@@ -14,8 +14,17 @@
 public final class GeoIp2Country extends Country {
     private final boolean isHighRisk;
 
-    // This method is for backwards compatibility. We should remove it when we
-    // do a major release.
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param locales The locales.
+     * @param confidence The confidence.
+     * @param geoNameId The GeoName ID.
+     * @param isHighRisk Whether it is a high risk country.
+     * @param isoCode The ISO code.
+     * @param names The names.
+     */
     public GeoIp2Country(
             List<String> locales,
             Integer confidence,

src/main/java/com/maxmind/minfraud/response/IpAddress.java

@@ -4,6 +4,8 @@
 import com.maxmind.geoip2.model.InsightsResponse;
 import com.maxmind.geoip2.record.*;
 
+import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -13,6 +15,7 @@ public final class IpAddress extends InsightsResponse implements IpAddressInterf
     private final GeoIp2Country country;
     private final GeoIp2Location location;
     private final Double risk;
+    private final List<IpRiskReason> riskReasons;
 
     public IpAddress(
             @JsonProperty("city") City city,
@@ -24,13 +27,48 @@ public IpAddress(
             @JsonProperty("registered_country") Country registeredCountry,
             @JsonProperty("represented_country") RepresentedCountry representedCountry,
             @JsonProperty("risk") Double risk,
+            @JsonProperty("risk_reasons") List<IpRiskReason> riskReasons,
             @JsonProperty("subdivisions") List<Subdivision> subdivisions,
             @JsonProperty("traits") Traits traits
     ) {
         super(city, continent, country, location, maxmind, postal, registeredCountry, representedCountry, subdivisions, traits);
         this.country = country == null ? new GeoIp2Country() : country;
         this.location = location == null ? new GeoIp2Location() : location;
         this.risk = risk;
+        this.riskReasons = Collections.unmodifiableList(riskReasons == null ? new ArrayList<>() : riskReasons);
+    }
+
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param city The city information.
+     * @param continent The continent information.
+     * @param country The country information.
+     * @param location The location information.
+     * @param maxmind MaxMind-specific information.
+     * @param postal The postal information.
+     * @param registeredCountry The information about the country where the IP was registered.
+     * @param representedCountry The represented country, e.g., for military bases in other countries.
+     * @param risk The IP risk.
+     * @param subdivisions The list of subdivisions.
+     * @param traits Information about various other IP traits.
+     */
+    public IpAddress(
+            City city,
+            Continent continent,
+            GeoIp2Country country,
+            GeoIp2Location location,
+            MaxMind maxmind,
+            Postal postal,
+            Country registeredCountry,
+            RepresentedCountry representedCountry,
+            Double risk,
+            List<Subdivision> subdivisions,
+            Traits traits
+    ) {
+        this(city, continent, country, location, maxmind, postal, registeredCountry, representedCountry,
+                risk, null, subdivisions, traits);
     }
 
     public IpAddress() {
@@ -63,4 +101,14 @@ public GeoIp2Location getLocation() {
     public Double getRisk() {
         return risk;
     }
+
+    /**
+     * @return An unmodifiable list containing risk reason objects that identify
+     * the reasons why the IP address received the associated risk. This will
+     * be an empty list if there are no reasons.
+     */
+    @JsonProperty("risk_reasons")
+    public final List<IpRiskReason> getRiskReasons() {
+        return riskReasons;
+    }
 }

src/main/java/com/maxmind/minfraud/response/IpRiskReason.java

@@ -0,0 +1,66 @@
+package com.maxmind.minfraud.response;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.maxmind.minfraud.AbstractModel;
+
+/**
+ * This class represents the reason for the IP risk.
+ */
+public final class IpRiskReason extends AbstractModel {
+    private final String code;
+    private final String reason;
+
+    public IpRiskReason(
+            @JsonProperty("code") String code,
+            @JsonProperty("reason") String reason
+    ) {
+        this.code = code;
+        this.reason = reason;
+    }
+
+    /**
+     * This provides a machine-readable code identifying the reason. Although
+     * more codes may be added in the future, the current codes are:
+     * <dl>
+     *     <dt>ANONYMOUS_IP</dt>
+     *     <dd>The IP address belongs to an anonymous network. See the
+     *     object at <code>.IPAddress.Traits</code> for more details.</dd>
+     *
+     *     <dt>BILLING_POSTAL_VELOCITY</dt>
+     *     <dd>Many different billing postal codes have been seen on
+     *     this IP address.</dd>
+     *
+     *     <dt>EMAIL_VELOCITY</dt>
+     *     <dd>Many different email addresses have been seen on this
+     *     IP address.</dd>
+     *
+     *     <dt>HIGH_RISK_DEVICE</dt>
+     *     <dd>A high risk device was seen on this IP address.</dd>
+     *
+     *     <dt>HIGH_RISK_EMAIL</dt>
+     *     <dd>A high risk email address was seen on this IP address in
+     *     your past transactions.</dd>
+     *
+     *     <dt>ISSUER_ID_NUMBER_VELOCITY</dt>
+     *     <dd>Many different issuer ID numbers have been seen on this
+     *     IP address.</dd>
+     *
+     *     <dt>MINFRAUD_NETWORK_ACTIVITY</dt>
+     *     <dd>Suspicious activity has been seen on this IP address
+     *     across minFraud customers.</dd>
+     * </dl>
+     *
+     * @return The reason code.
+     */
+    public String getCode() {
+        return this.code;
+    }
+
+    /**
+     * @return This field provides a human-readable explanation of the reason.
+     * The description may change at any time and should not be matched against.
+     */
+    public String getReason() {
+        return this.reason;
+    }
+}

src/main/java/com/maxmind/minfraud/response/ScoreResponse.java

@@ -93,8 +93,8 @@ public final Double getRiskScore() {
     }
 
     /**
-     * @return An unmodifiable list contains warning objects detailing issues
-     * with the request that was sent such as invalid or unknown inputs. It is
+     * @return An unmodifiable list containing warning objects that detail
+     * issues with the request such as invalid or unknown inputs. It is
      * highly recommended that you check this list for issues when integrating
      * the web service.
      */

src/main/java/com/maxmind/minfraud/response/Subscores.java

@@ -72,8 +72,28 @@ public Subscores(
         this.timeOfDay = timeOfDay;
     }
 
-    // This method is for backwards compatibility. We should remove it when we
-    // do a major release.
+    /**
+     * @deprecated This constructor only exists for backward compatibility
+     * and will be removed in the next major release.
+     *
+     * @param avsResult The AVS result subscore.
+     * @param billingAddress The billing address subscore.
+     * @param billingAddressDistanceToIpLocation The billing address distance to the IP location subscore.
+     * @param browser The browser subscore.
+     * @param chargeback The chargeback subscore.
+     * @param country The country subscore.
+     * @param countryMismatch The country mismatch subscore.
+     * @param cvvResult The CVV result subscore.
+     * @param emailAddress The email address subscore.
+     * @param emailDomain The email domain subscore.
+     * @param emailTenure The email tenure subscore.
+     * @param ipTenure The IP tenure subscore.
+     * @param issuerIdNumber The IIN subscore.
+     * @param orderAmount The order amount subscore.
+     * @param phoneNumber The phone number subscore.
+     * @param shippingAddressDistanceToIpLocation The shipping address distance to IP location subscore.
+     * @param timeOfDay The time of day subscore.
+     */
     public Subscores(
             Double avsResult,
             Double billingAddress,