Add risk score reasons

CHANGELOG.md

@@ -1,6 +1,14 @@
 CHANGELOG
 =========
 
+3.2.0-beta.1
+------------------
+
+* Added support for the new risk reasons outputs in minFraud Factors. The risk
+  reasons output codes and reasons are currently in beta and are subject to
+  change. We recommend that you use these beta outputs with caution and avoid
+  relying on them for critical applications.
+
 3.1.0 (2024-07-08)
 ------------------
 

src/MinFraud/Model/Factors.php

@@ -9,6 +9,16 @@
  */
 class Factors extends Insights
 {
+    /**
+     * @var array<RiskScoreReason> This array contains \MaxMind\MinFraud\Model\RiskScoreReason
+     *                             objects that describe risk score reasons for a given transaction
+     *                             that change the risk score significantly. Risk score reasons are
+     *                             usually only returned for medium to high risk transactions.
+     *                             If there were no significant changes to the risk score due to
+     *                             these reasons, then this array will be empty.
+     */
+    public readonly array $riskScoreReasons;
+
     /**
      * @var Subscores an object containing scores for many of the individual
      *                risk factors that are used to calculate the overall risk
@@ -20,6 +30,14 @@ public function __construct(array $response, array $locales = ['en'])
     {
         parent::__construct($response, $locales);
 
+        $riskScoreReasons = [];
+        if (isset($response['risk_score_reasons'])) {
+            foreach ($response['risk_score_reasons'] as $reason) {
+                $riskScoreReasons[] = new RiskScoreReason($reason);
+            }
+        }
+        $this->riskScoreReasons = $riskScoreReasons;
+
         $this->subscores
             = new Subscores($response['subscores'] ?? []);
     }
@@ -28,6 +46,14 @@ public function jsonSerialize(): array
     {
         $js = parent::jsonSerialize();
 
+        if (!empty($this->riskScoreReasons)) {
+            $riskScoreReasons = [];
+            foreach ($this->riskScoreReasons as $reason) {
+                $riskScoreReasons[] = $reason->jsonSerialize();
+            }
+            $js['risk_score_reasons'] = $riskScoreReasons;
+        }
+
         $subscores = $this->subscores->jsonSerialize();
         if (!empty($subscores)) {
             $js['subscores'] = $subscores;

src/MinFraud/Model/Reason.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MaxMind\MinFraud\Model;
+
+/**
+ * The risk score reason for the multiplier.
+ *
+ * This class provides both a machine-readable code and a human-readable
+ * explanation of the reason for the risk score, see
+ * {@link https://dev.maxmind.com/minfraud/api-documentation/responses/#schema--response--risk-score-reason--multiplier-reason}.
+ *
+ * Although more codes may be added in the future, the current codes are:
+ *
+ * * `BROWSER_LANGUAGE` - Riskiness of the browser user-agent and language associated with the request.
+ * * `BUSINESS_ACTIVITY` - Riskiness of business activity associated with the request.
+ * * `COUNTRY` - Riskiness of the country associated with the request.
+ * * `CUSTOMER_ID` - Riskiness of a customer's activity.
+ * * `EMAIL_DOMAIN` - Riskiness of email domain.
+ * * `EMAIL_DOMAIN_NEW` - Riskiness of newly-sighted email domain.
+ * * `EMAIL_ADDRESS_NEW` - Riskiness of newly-sighted email address.
+ * * `EMAIL_LOCAL_PART` - Riskiness of the local part of the email address.
+ * * `EMAIL_VELOCITY` - Velocity on email - many requests on same email over short period of time.
+ * * `ISSUER_ID_NUMBER_COUNTRY_MISMATCH` - Riskiness of the country mismatch between IP, billing,
+ *    shipping and IIN country.
+ * * `ISSUER_ID_NUMBER_ON_SHOP_ID` - Risk of Issuer ID Number for the shop ID.
+ * * `ISSUER_ID_NUMBER_LAST_DIGITS_ACTIVITY` - Riskiness of many recent requests and previous
+ *    high-risk requests on the IIN and last digits of the credit card.
+ * * `ISSUER_ID_NUMBER_SHOP_ID_VELOCITY` - Risk of recent Issuer ID Number activity for the shop ID.
+ * * `INTRACOUNTRY_DISTANCE` - Risk of distance between IP, billing, and shipping location.
+ * * `ANONYMOUS_IP` - Risk due to IP being an Anonymous IP.
+ * * `IP_BILLING_POSTAL_VELOCITY` - Velocity of distinct billing postal code on IP address.
+ * * `IP_EMAIL_VELOCITY` - Velocity of distinct email address on IP address.
+ * * `IP_HIGH_RISK_DEVICE` - High-risk device sighted on IP address.
+ * * `IP_ISSUER_ID_NUMBER_VELOCITY` - Velocity of distinct IIN on IP address.
+ * * `IP_ACTIVITY` - Riskiness of IP based on minFraud network activity.
+ * * `LANGUAGE` - Riskiness of browser language.
+ * * `MAX_RECENT_EMAIL` - Riskiness of email address based on past minFraud risk scores on email.
+ * * `MAX_RECENT_PHONE` - Riskiness of phone number based on past minFraud risk scores on phone.
+ * * `MAX_RECENT_SHIP` - Riskiness of email address based on past minFraud risk scores on ship address.
+ * * `MULTIPLE_CUSTOMER_ID_ON_EMAIL` - Riskiness of email address having many customer IDs.
+ * * `ORDER_AMOUNT` - Riskiness of the order amount.
+ * * `ORG_DISTANCE_RISK` - Risk of ISP and distance between billing address and IP location.
+ * * `PHONE` - Riskiness of the phone number or related numbers.
+ * * `CART` - Riskiness of shopping cart contents.
+ * * `TIME_OF_DAY` - Risk due to local time of day.
+ * * `TRANSACTION_REPORT_EMAIL` - Risk due to transaction reports on the email address.
+ * * `TRANSACTION_REPORT_IP` - Risk due to transaction reports on the IP address.
+ * * `TRANSACTION_REPORT_PHONE` - Risk due to transaction reports on the phone number.
+ * * `TRANSACTION_REPORT_SHIP` - Risk due to transaction reports on the shipping address.
+ * * `EMAIL_ACTIVITY` - Riskiness of the email address based on minFraud network activity.
+ * * `PHONE_ACTIVITY` - Riskiness of the phone number based on minFraud network activity.
+ * * `SHIP_ACTIVITY` - Riskiness of ship address based on minFraud network activity.
+ */
+class Reason implements \JsonSerializable
+{
+    /**
+     * @var string This value is a machine-readable code identifying the reason
+     */
+    public readonly string $code;
+
+    /**
+     * @var string This value provides a human-readable explanation of the reason. The description
+     *             may change at any time and should not be matched against.
+     */
+    public readonly string $reason;
+
+    public function __construct(array $response)
+    {
+        $this->code = $response['code'];
+        $this->reason = $response['reason'];
+    }
+
+    public function jsonSerialize(): array
+    {
+        $js = [];
+
+        $js['code'] = $this->code;
+        $js['reason'] = $this->reason;
+
+        return $js;
+    }
+}

src/MinFraud/Model/RiskScoreReason.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MaxMind\MinFraud\Model;
+
+/**
+ * The risk score multiplier and the reasons for that multiplier.
+ */
+class RiskScoreReason implements \JsonSerializable
+{
+    /**
+     * @var float|null The factor by which the risk score is increased (if the value is greater than 1)
+     *                 or decreased (if the value is less than 1) for given risk reason(s).
+     *                 Multipliers greater than 1.5 and less than 0.66 are considered significant
+     *                 and lead to risk reason(s) being present.
+     */
+    public readonly ?float $multiplier;
+
+    /**
+     * @var array<Reason> This array contains \MaxMind\MinFraud\Model\Reason objects that describe
+     *                    one of the reasons for the multiplier
+     */
+    public readonly array $reasons;
+
+    public function __construct(?array $response)
+    {
+        if ($response === null) {
+            $response = [];
+        }
+
+        $this->multiplier = $response['multiplier'] ?? null;
+
+        $reasons = [];
+        if (isset($response['reasons'])) {
+            foreach ($response['reasons'] as $reason) {
+                $reasons[] = new Reason($reason);
+            }
+        }
+        $this->reasons = $reasons;
+    }
+
+    public function jsonSerialize(): ?array
+    {
+        $js = [];
+
+        if ($this->multiplier !== null) {
+            $js['multiplier'] = $this->multiplier;
+        }
+
+        if (!empty($this->reasons)) {
+            $reasons = [];
+            foreach ($this->reasons as $reason) {
+                $reasons[] = $reason->jsonSerialize();
+            }
+            $js['reasons'] = $reasons;
+        }
+
+        return $js;
+    }
+}

tests/MaxMind/Test/MinFraud/Model/FactorsTest.php

@@ -55,5 +55,20 @@ public function testFactorsProperties(): void
                 $key
             );
         }
+
+        $this->assertCount(4, $factors->riskScoreReasons);
+        $this->assertSame(
+            $array['risk_score_reasons'][0]['multiplier'],
+            $factors->riskScoreReasons[0]->multiplier,
+        );
+        $this->assertCount(1, $factors->riskScoreReasons[0]->reasons);
+        $this->assertSame(
+            $array['risk_score_reasons'][0]['reasons'][0]['code'],
+            $factors->riskScoreReasons[0]->reasons[0]->code,
+        );
+        $this->assertSame(
+            $array['risk_score_reasons'][0]['reasons'][0]['reason'],
+            $factors->riskScoreReasons[0]->reasons[0]->reason,
+        );
     }
 }

tests/MaxMind/Test/MinFraud/Model/ReasonTest.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MaxMind\Test\MinFraud\Model;
+
+use MaxMind\MinFraud\Model\Reason;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @coversNothing
+ *
+ * @internal
+ */
+class ReasonTest extends TestCase
+{
+    public function testReason(): void
+    {
+        $array = [
+            'code' => 'ANONYMOUS_IP',
+            'reason' => 'Risk due to IP being an Anonymous IP',
+        ];
+        $reason = new Reason($array);
+
+        $this->assertSame(
+            $array['code'],
+            $reason->code,
+            'code'
+        );
+
+        $this->assertSame(
+            $array['reason'],
+            $reason->reason,
+            'reason'
+        );
+
+        $this->assertSame(
+            $array,
+            $reason->jsonSerialize(),
+            'correctly implements JsonSerializable'
+        );
+    }
+}

tests/MaxMind/Test/MinFraud/Model/RiskScoreReasonTest.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MaxMind\Test\MinFraud\Model;
+
+use MaxMind\MinFraud\Model\RiskScoreReason;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @coversNothing
+ *
+ * @internal
+ */
+class RiskScoreReasonTest extends TestCase
+{
+    public function testRiskScoreReason(): void
+    {
+        $array = [
+            'multiplier' => 45.0,
+            'reasons' => [
+                [
+                    'code' => 'ANONYMOUS_IP',
+                    'reason' => 'Risk due to IP being an Anonymous IP',
+                ],
+            ],
+        ];
+
+        $reason = new RiskScoreReason($array);
+
+        $this->assertSame(
+            $array['multiplier'],
+            $reason->multiplier,
+            'multiplier'
+        );
+
+        $this->assertSame(
+            \count($array['reasons']),
+            \count($reason->reasons),
+            'correct number of reasons'
+        );
+
+        $this->assertSame(
+            $array['reasons'][0]['code'],
+            $reason->reasons[0]->code,
+            'correct code'
+        );
+
+        $this->assertSame(
+            $array['reasons'][0]['reason'],
+            $reason->reasons[0]->reason,
+            'correct reason'
+        );
+    }
+}

tests/data/minfraud/factors-response.json

@@ -200,5 +200,43 @@
       "input_pointer": "/account/username_md5",
       "warning": "Encountered value at /account/username_md5 that does meet the required constraints"
     }
+  ],
+  "risk_score_reasons": [
+    {
+      "multiplier": 45.0,
+      "reasons": [
+        {
+          "code": "ANONYMOUS_IP",
+          "reason": "Risk due to IP being an Anonymous IP"
+        }
+      ]
+    },
+    {
+      "multiplier": 1.8,
+      "reasons": [
+        {
+          "code": "TIME_OF_DAY",
+          "reason": "Risk due to local time of day"
+        }
+      ]
+    },
+    {
+      "multiplier": 1.6,
+      "reasons": [
+        {
+          "reason": "Riskiness of newly-sighted email domain",
+          "code": "EMAIL_DOMAIN_NEW"
+        }
+      ]
+    },
+    {
+      "multiplier": 0.34,
+      "reasons": [
+        {
+          "code": "EMAIL_ADDRESS_NEW",
+          "reason": "Riskiness of newly-sighted email address"
+        }
+      ]
+    }
   ]
 }