Add new field card pan

README.md

@@ -230,6 +230,8 @@ You may provide the following as envelopes:
 
 <a name="changelog"></a>
 ## Changelog
+* `1.5.4`
+  * Added optional `card_pan` field for transaction, payout events
 * `1.5.3`
   * Added optional `deepfake` and `deepfake_confidence` fields for document event
 * `1.5.2`

src/Envelopes/Builder.php

@@ -272,6 +272,7 @@ public static function registrationEvent(
      * @param string|null $groupId
      * @param string|null $linksToDocuments
      * @param array|null $documentId
+     * @param int|null $cardPan
      *
      * @return Builder
      */
@@ -299,7 +300,8 @@ public static function payoutEvent(
         $cardExpirationYear = null,
         $groupId = null,
         $linksToDocuments = null,
-        $documentId = null
+        $documentId = null,
+        $cardPan = null
     ) {
         $builder = new self('payout', $sequenceId);
         if ($payoutTimestamp === null) {
@@ -325,7 +327,8 @@ public static function payoutEvent(
             ->addShortUserData($email, $userId, $phone, $firstName, $lastName, $country)
             ->addGroupId($groupId)
             ->addLinksToDocuments($linksToDocuments)
-            ->addDocumentData($documentId);
+            ->addDocumentData($documentId)
+            ->addCardPan($cardPan);
     }
 
     /**
@@ -379,6 +382,7 @@ public static function payoutEvent(
      * @param string|null $groupId
      * @param string|null $linksToDocuments
      * @param array|null $documentId
+     * @param int|null $cardPan
      *
      * @return Builder
      */
@@ -430,7 +434,8 @@ public static function transactionEvent(
         $acquirerMerchantId = null,
         $groupId = null,
         $linksToDocuments = null,
-        $documentId = null
+        $documentId = null,
+        $cardPan = null
     ) {
         $builder = new self('transaction', $sequenceId);
         if ($transactionTimestamp === null) {
@@ -482,8 +487,8 @@ public static function transactionEvent(
             ->addIpData(null, null, $merchantIp)
             ->addGroupId($groupId)
             ->addLinksToDocuments($linksToDocuments)
-            ->addDocumentData($documentId);
-
+            ->addDocumentData($documentId)
+            ->addCardPan($cardPan);
     }
 
     /**
@@ -4044,6 +4049,22 @@ public function addDocumentData($documentId = null)
         return $this;
     }
 
+    /**
+     * Provides card pan value to envelope
+     *
+     * @param int|null $cardPan
+     * @return $this
+     */
+    public function addCardPan($cardPan = null)
+    {
+        if ($cardPan !== null && !is_int($cardPan)) {
+            throw new \InvalidArgumentException('Card Pan must be int');
+        }
+        $this->replace('card_pan', $cardPan);
+
+        return $this;
+    }
+
     /**
      * Add links to documents
      *

src/Envelopes/ValidatorV1.php

@@ -272,6 +272,7 @@ class ValidatorV1
         'translated_extracted_text' => 'string(225)',
         'translated_from' => 'string(225)',
         'translated_to' => 'string(225)',
+        'card_pan' => 'int',
         'deepfake' => 'bool',
         'deepfake_confidence' => 'float'
     );
@@ -325,6 +326,8 @@ class ValidatorV1
         'client_resolution'
     );
 
+    private static $cardPanKey = 'card_pan';
+
     private static $types = array(
         'confirmation' => array(
             'mandatory' => array('confirmation_timestamp', 'user_merchant_id'),
@@ -417,6 +420,7 @@ class ValidatorV1
                 'group_id',
                 'links_to_documents',
                 'document_id',
+                'card_pan',
             )
         ),
         'payout' => array(
@@ -446,6 +450,7 @@ class ValidatorV1
                 'group_id',
                 'links_to_documents',
                 'document_id',
+                'card_pan',
             )
         ),
         'install' => array(
@@ -1216,6 +1221,69 @@ public function analyzeFieldTypes(EnvelopeInterface $envelope)
         return array();
     }
 
+    /**
+     * Analyzes card pan
+     *
+     * @param int|null $cardPan
+     * @return array
+     */
+    public function analyzeCardPan(int $cardPan = null)
+    {
+        $details = array();
+        if (!empty($cardPan)) {
+            $numberStr = (string)$cardPan;
+
+            $length = strlen($numberStr);
+            if ($length < 14) {
+                $details[] = sprintf(
+                    'Field "%s" must contain at least 14 digits, but only %d provided (%s)',
+                    self::$cardPanKey,
+                    $length,
+                    $numberStr
+                );
+            }
+
+            if ($length > 19) {
+                $details[] = sprintf(
+                    'Field "%s" must not exceed 19 digits, but %d provided (%s)',
+                    self::$cardPanKey,
+                    $length,
+                    $numberStr
+                );
+            }
+
+            if (!empty($details)) {
+                return $details;
+            }
+
+            $sum = 0;
+            $alt = false;
+
+            for ($i = $length - 1; $i >= 0; $i--) {
+                $n = (int)$numberStr[$i];
+                if ($alt) {
+                    $n *= 2;
+                    if ($n > 9) {
+                        $n -= 9;
+                    }
+                }
+                $sum += $n;
+                $alt = !$alt;
+            }
+
+            if ($sum % 10 !== 0) {
+                $details[] = sprintf(
+                    'Field "%s" failed Luhn validation (sum mod 10 = %d)',
+                    self::$cardPanKey,
+                    $sum % 10
+                );
+            }
+            return $details;
+        }
+
+        return array();
+    }
+
     /**
      * Checks envelope validity and throws an exception on error
      *
@@ -1234,7 +1302,8 @@ public function validate(EnvelopeInterface $envelope)
                 $this->analyzeSequenceId($envelope->getSequenceId()),
                 $this->analyzeIdentities($envelope->getIdentities()),
                 $this->analyzeTypeAndMandatoryFields($envelope),
-                $this->analyzeFieldTypes($envelope)
+                $this->analyzeFieldTypes($envelope),
+                $this->analyzeCardPan(!empty($envelope[self::$cardPanKey]) ? $envelope[self::$cardPanKey] : null)
             );
         }
 

tests/Covery/BuildPayoutEventTest.php

@@ -33,13 +33,14 @@ public function testBuild()
             22,
             "group id value",
             'links to documents',
-            [1, 2]
+            [1, 2],
+            5555555555554444
         )->addBrowserData('88889', 'Test curl')->addIdentity(new \Covery\Client\Identities\Stub())->build();
 
         self::assertSame('payout', $result->getType());
         self::assertCount(1, $result->getIdentities());
         self::assertSame('someSequenceId', $result->getSequenceId());
-        self::assertCount(25, $result);
+        self::assertCount(26, $result);
         self::assertSame('fooUserId', $result['user_merchant_id']);
         self::assertSame(5566, $result['payout_timestamp']);
         self::assertSame('payoutLargeId', $result['payout_id']);
@@ -157,4 +158,76 @@ public function testEventExpectInvalidArgumentExceptionForNegativeAmountConverte
             -2
         )->build();
     }
+
+    public function testAnalyzeCardPanThrowsForTooShortCardPan()
+    {
+        // Card Pan to short
+        $validator = new \Covery\Client\Envelopes\ValidatorV1();
+        $this->expectException(\Covery\Client\EnvelopeValidationException::class);
+        $this->expectExceptionMessage("Field \"card_pan\" must contain at least 14 digits, but only 8 provided (55555555)");
+        $result = \Covery\Client\Envelopes\Builder::payoutEvent(
+            'someSequenceId',
+            'fooUserId',
+            'payoutLargeId',
+            'GBP',
+            0.12,
+            5566,
+            'someCard0001',
+            'someAccountId',
+            'mtd',
+            'sts',
+            'midnight',
+            23,
+            'tony',
+            'hawk',
+            'zimbabwe',
+            'jjj@xx.zzz',
+            '+323423234',
+            123456,
+            '4445',
+            11,
+            22,
+            "group id value",
+            'links to documents',
+            [1, 2],
+            55555555
+        )->build();
+        $validator->validate($result);
+    }
+
+    public function testAnalyzeCardPanThrowsForBadChecksum()
+    {
+        // Card Pan bad checksum
+        $validator = new \Covery\Client\Envelopes\ValidatorV1();
+        $this->expectException(\Covery\Client\EnvelopeValidationException::class);
+        $this->expectExceptionMessage("Field \"card_pan\" failed Luhn validation (sum mod 10 = 9)");
+        $result = \Covery\Client\Envelopes\Builder::payoutEvent(
+            'someSequenceId',
+            'fooUserId',
+            'payoutLargeId',
+            'GBP',
+            0.12,
+            5566,
+            'someCard0001',
+            'someAccountId',
+            'mtd',
+            'sts',
+            'midnight',
+            23,
+            'tony',
+            'hawk',
+            'zimbabwe',
+            'jjj@xx.zzz',
+            '+323423234',
+            123456,
+            '4445',
+            11,
+            22,
+            "group id value",
+            'links to documents',
+            [1, 2],
+            5555555555554443
+        )->build();
+        $validator->validate($result);
+    }
 }