From 54c1ceffe518617fbc29dd6b4a6552fba20e9107 Mon Sep 17 00:00:00 2001
From: Marsel Mavletkulov <mmavletkulov@maxmind.com>
Date: Thu, 29 Aug 2024 17:08:17 -0400
Subject: [PATCH] Add risk score reasons

---
 CHANGELOG.md                                  |   8 ++
 src/MinFraud/Model/Factors.php                |  26 +++++
 src/MinFraud/Model/Reason.php                 | 104 ++++++++++++++++++
 src/MinFraud/Model/RiskScoreReason.php        |  61 ++++++++++
 .../Test/MinFraud/Model/FactorsTest.php       |   9 ++
 .../Test/MinFraud/Model/ReasonTest.php        |  43 ++++++++
 .../MinFraud/Model/RiskScoreReasonTest.php    |  55 +++++++++
 tests/data/minfraud/factors-response.json     |  38 +++++++
 8 files changed, 344 insertions(+)
 create mode 100644 src/MinFraud/Model/Reason.php
 create mode 100644 src/MinFraud/Model/RiskScoreReason.php
 create mode 100644 tests/MaxMind/Test/MinFraud/Model/ReasonTest.php
 create mode 100644 tests/MaxMind/Test/MinFraud/Model/RiskScoreReasonTest.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 598b575..1973860 100644
--- a/CHANGELOG.md
+++ b/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)
 ------------------
 
diff --git a/src/MinFraud/Model/Factors.php b/src/MinFraud/Model/Factors.php
index b297ffd..6a0ebef 100644
--- a/src/MinFraud/Model/Factors.php
+++ b/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;
diff --git a/src/MinFraud/Model/Reason.php b/src/MinFraud/Model/Reason.php
new file mode 100644
index 0000000..61442a2
--- /dev/null
+++ b/src/MinFraud/Model/Reason.php
@@ -0,0 +1,104 @@
+<?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 property 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'] ?? null;
+        $this->reason = $response['reason'] ?? null;
+    }
+
+    public function jsonSerialize(): array
+    {
+        $js = [];
+
+        if ($this->code !== null) {
+            $js['code'] = $this->code;
+        }
+        if ($this->reason !== null) {
+            $js['reason'] = $this->reason;
+        }
+
+        return $js;
+    }
+}
diff --git a/src/MinFraud/Model/RiskScoreReason.php b/src/MinFraud/Model/RiskScoreReason.php
new file mode 100644
index 0000000..7dcf001
--- /dev/null
+++ b/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;
+    }
+}
diff --git a/tests/MaxMind/Test/MinFraud/Model/FactorsTest.php b/tests/MaxMind/Test/MinFraud/Model/FactorsTest.php
index dc133d6..abffed1 100644
--- a/tests/MaxMind/Test/MinFraud/Model/FactorsTest.php
+++ b/tests/MaxMind/Test/MinFraud/Model/FactorsTest.php
@@ -55,5 +55,14 @@ public function testFactorsProperties(): void
                 $key
             );
         }
+
+        $this->assertSame(
+            $array['risk_score_reasons'][0]['multiplier'],
+            $factors->riskScoreReasons[0]->multiplier,
+        );
+        $this->assertSame(
+            $array['risk_score_reasons'][0]['reasons'][0]['code'],
+            $factors->riskScoreReasons[0]->reasons[0]->code,
+        );
     }
 }
diff --git a/tests/MaxMind/Test/MinFraud/Model/ReasonTest.php b/tests/MaxMind/Test/MinFraud/Model/ReasonTest.php
new file mode 100644
index 0000000..6bf3b4d
--- /dev/null
+++ b/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'
+        );
+    }
+}
diff --git a/tests/MaxMind/Test/MinFraud/Model/RiskScoreReasonTest.php b/tests/MaxMind/Test/MinFraud/Model/RiskScoreReasonTest.php
new file mode 100644
index 0000000..5561999
--- /dev/null
+++ b/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'
+        );
+    }
+}
diff --git a/tests/data/minfraud/factors-response.json b/tests/data/minfraud/factors-response.json
index 71e15c3..f6740eb 100644
--- a/tests/data/minfraud/factors-response.json
+++ b/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"
+        }
+      ]
+    }
   ]
 }