Add new matches_postal phone property

Author: oschwald

CHANGELOG.md

@@ -4,6 +4,9 @@ CHANGELOG
 3.4.0
 ------------------
 
+* Added support for the `/billing_phone/matches_postal` and
+  `/shipping_phone/matches_postal` outputs. These are available as the
+  `matchesPostal` property on `MaxMind\MinFraud\Model\Phone`.
 * Added `cryptomus` to the payment processor validation.
 
 3.3.0

src/MinFraud/Model/Phone.php

@@ -24,6 +24,16 @@ class Phone implements \JsonSerializable
      */
     public readonly ?bool $isVoip;
 
+    /**
+     * @var bool|null This is `true` if the phone number's prefix is commonly
+     *                associated with the postal code. It is `false` if the
+     *                prefix is not associated with the postal code. It
+     *                is non-`null` only when the phone number is in the US,
+     *                the number prefix is in our database, and the postal
+     *                code and country are provided in the request.
+     */
+    public readonly ?bool $matchesPostal;
+
     /**
      * @var string|null The name of the original network operator associated with
      *                  the phone number. This property does not reflect phone numbers
@@ -45,6 +55,7 @@ public function __construct(?array $response)
     {
         $this->country = $response['country'] ?? null;
         $this->isVoip = $response['is_voip'] ?? null;
+        $this->matchesPostal = $response['matches_postal'] ?? null;
         $this->networkOperator = $response['network_operator'] ?? null;
         $this->numberType = $response['number_type'] ?? null;
     }
@@ -64,6 +75,10 @@ public function jsonSerialize(): array
             $js['is_voip'] = $this->isVoip;
         }
 
+        if ($this->matchesPostal !== null) {
+            $js['matches_postal'] = $this->matchesPostal;
+        }
+
         if ($this->networkOperator !== null) {
             $js['network_operator'] = $this->networkOperator;
         }

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

@@ -19,6 +19,7 @@ public function testPhone(): void
         $array = [
             'country' => 'US',
             'is_voip' => true,
+            'matches_postal' => false,
             'network_operator' => 'Verizon/1',
             'number_type' => 'fixed',
         ];
@@ -36,6 +37,12 @@ public function testPhone(): void
             'isVoip'
         );
 
+        $this->assertSame(
+            $array['matches_postal'],
+            $phone->matchesPostal,
+            'matchesPostal'
+        );
+
         $this->assertSame(
             $array['network_operator'],
             $phone->networkOperator,

tests/data/minfraud/factors-response.json

@@ -123,6 +123,7 @@
   "billing_phone": {
     "country": "US",
     "is_voip": true,
+    "matches_postal": true,
     "network_operator": "Verizon/1",
     "number_type": "fixed"
   },
@@ -166,6 +167,7 @@
   "shipping_phone": {
     "country": "CA",
     "is_voip": true,
+    "matches_postal": true,
     "network_operator": "Telus Mobility-SVR/2",
     "number_type": "mobile"
   },

tests/data/minfraud/insights-response.json

@@ -123,6 +123,7 @@
   "billing_phone": {
     "country": "US",
     "is_voip": true,
+    "matches_postal": true,
     "network_operator": "Verizon/1",
     "number_type": "fixed"
   },
@@ -166,6 +167,7 @@
   "shipping_phone": {
     "country": "CA",
     "is_voip": true,
+    "matches_postal": true,
     "network_operator": "Telus Mobility-SVR/2",
     "number_type": "mobile"
   },