Add support for 8 digit IINs and 2 digit last_digits

Previously issuer_id_number was expected to be 6 digits and
last_4_digits to be 4 digits. This changes the validation to
additionally allow for 8 digit issuer_id_numbers + 2 digit
last_4_digits.

Additionally last_4_digits has been deprecated in favor of the
more appropriately named last_digits.

Author: ugexe

README.rst

@@ -191,10 +191,10 @@ Score, Insights and Factors Example
     >>>         'bank_phone_country_code': '1',
     >>>         'avs_result': 'Y',
     >>>         'bank_phone_number': '123-456-1234',
-    >>>         'last_4_digits': '7643',
+    >>>         'last_digits': '7643',
     >>>         'cvv_result': 'N',
     >>>         'bank_name': 'Bank of No Hope',
-    >>>         'issuer_id_number': '411111'
+    >>>         'issuer_id_number': '411111',
     >>>         'was_3d_secure_successful': True
     >>>     },
     >>>     'payment': {

minfraud/request.py

@@ -5,6 +5,7 @@
 
 """
 
+import warnings
 import hashlib
 from typing import Any, Dict
 from voluptuous import MultipleInvalid
@@ -53,6 +54,9 @@ def prepare_transaction(
     if hash_email:
         maybe_hash_email(cleaned_request)
 
+    if cleaned_request.get("credit_card", None):
+        clean_credit_card(cleaned_request)
+
     return cleaned_request
 
 
@@ -65,6 +69,17 @@ def _copy_and_clean(data: Any) -> Any:
     return data
 
 
+def clean_credit_card(transaction):
+    """Clean the credit_card input of a transaction request"""
+    last4 = transaction["credit_card"].pop("last_4_digits", None)
+    if last4:
+        warnings.warn(
+            "last_4_digits has been deprecated in favor of last_digits",
+            DeprecationWarning,
+        )
+        transaction["credit_card"]["last_digits"] = last4
+
+
 def maybe_hash_email(transaction):
     """Hash email address in transaction, if present"""
     try:

minfraud/validation.py

@@ -7,7 +7,6 @@
 
 """
 
-
 import ipaddress
 import re
 import uuid
@@ -17,7 +16,7 @@
 
 from email_validator import validate_email  # type: ignore
 from voluptuous import All, Any, In, Match, Range, Required, Schema
-from voluptuous.error import UrlInvalid
+from voluptuous.error import LengthInvalid, UrlInvalid
 
 # Pylint doesn't like the private function type naming for the callable
 # objects below. Given the consistent use of them, the current names seem
@@ -250,9 +249,9 @@ def _hostname(hostname: str) -> str:
 
 _single_char = Match("^[A-Za-z0-9]$")
 
-_iin = Match("^[0-9]{6}$")
+_iin = Match("^(?:[0-9]{6}|[0-9]{8})$")
 
-_credit_card_last_4 = Match("^[0-9]{4}$")
+_credit_card_last_digits = Match("^(?:[0-9]{2}|[0-9]{4})$")
 
 
 def _credit_card_token(s: str) -> str:
@@ -292,67 +291,94 @@ def _uri(s: str) -> str:
     return s
 
 
+def _validate_last_digits(req):
+    cc = req.get("credit_card")
+    if cc is None:
+        return
+
+    iin = cc.get("issuer_id_number")
+    if iin is None:
+        return
+
+    if iin and len(iin) == 8:
+        last_digits = cc.get("last_digits")
+        last_4_digits = cc.get("last_4_digits")
+        if last_digits and len(last_digits) != 2:
+            raise LengthInvalid(
+                "last_digits must be two digits when the issuer_id_number is eight digits."
+            )
+        if last_4_digits and len(last_4_digits) != 2:
+            raise LengthInvalid(
+                "last_4_digits must be two digits when the issuer_id_number is eight digits."
+            )
+    return
+
+
 validate_transaction = Schema(
-    {
-        "account": {
-            "user_id": str,
-            "username_md5": _md5,
-        },
-        "billing": _address,
-        "payment": {
-            "processor": _payment_processor,
-            "was_authorized": bool,
-            "decline_code": str,
-        },
-        "credit_card": {
-            "avs_result": _single_char,
-            "bank_name": str,
-            "bank_phone_country_code": _telephone_country_code,
-            "bank_phone_number": str,
-            "cvv_result": _single_char,
-            "issuer_id_number": _iin,
-            "last_4_digits": _credit_card_last_4,
-            "token": _credit_card_token,
-            "was_3d_secure_successful": bool,
-        },
-        "custom_inputs": {_custom_input_key: _custom_input_value},
-        "device": {
-            "accept_language": str,
-            "ip_address": _ip_address,
-            "session_age": All(_any_number, Range(min=0)),
-            "session_id": str,
-            "user_agent": str,
-        },
-        "email": {
-            "address": _email_or_md5,
-            "domain": _hostname,
-        },
-        "event": {
-            "shop_id": str,
-            "time": _rfc3339_datetime,
-            "type": _event_type,
-            "transaction_id": str,
-        },
-        "order": {
-            "affiliate_id": str,
-            "amount": _price,
-            "currency": _currency_code,
-            "discount_code": str,
-            "has_gift_message": bool,
-            "is_gift": bool,
-            "referrer_uri": _uri,
-            "subaffiliate_id": str,
-        },
-        "shipping": _shipping_address,
-        "shopping_cart": [
-            {
-                "category": str,
-                "item_id": str,
-                "price": _price,
-                "quantity": All(int, Range(min=1)),
+    All(
+        {
+            "account": {
+                "user_id": str,
+                "username_md5": _md5,
             },
-        ],
-    },
+            "billing": _address,
+            "payment": {
+                "processor": _payment_processor,
+                "was_authorized": bool,
+                "decline_code": str,
+            },
+            "credit_card": {
+                "avs_result": _single_char,
+                "bank_name": str,
+                "bank_phone_country_code": _telephone_country_code,
+                "bank_phone_number": str,
+                "cvv_result": _single_char,
+                "issuer_id_number": _iin,
+                "last_digits": _credit_card_last_digits,
+                "last_4_digits": _credit_card_last_digits,
+                "token": _credit_card_token,
+                "was_3d_secure_successful": bool,
+            },
+            "custom_inputs": {_custom_input_key: _custom_input_value},
+            "device": {
+                "accept_language": str,
+                "ip_address": _ip_address,
+                "session_age": All(_any_number, Range(min=0)),
+                "session_id": str,
+                "user_agent": str,
+            },
+            "email": {
+                "address": _email_or_md5,
+                "domain": _hostname,
+            },
+            "event": {
+                "shop_id": str,
+                "time": _rfc3339_datetime,
+                "type": _event_type,
+                "transaction_id": str,
+            },
+            "order": {
+                "affiliate_id": str,
+                "amount": _price,
+                "currency": _currency_code,
+                "discount_code": str,
+                "has_gift_message": bool,
+                "is_gift": bool,
+                "referrer_uri": _uri,
+                "subaffiliate_id": str,
+            },
+            "shipping": _shipping_address,
+            "shopping_cart": [
+                {
+                    "category": str,
+                    "item_id": str,
+                    "price": _price,
+                    "quantity": All(int, Range(min=1)),
+                },
+            ],
+        },
+        _validate_last_digits,
+    )
 )
 
 

tests/data/full-transaction-request.json

@@ -47,7 +47,7 @@
   },
   "credit_card": {
     "issuer_id_number": "411111",
-    "last_4_digits": "7643",
+    "last_digits": "7643",
     "bank_name": "Bank of No Hope",
     "bank_phone_country_code": "1",
     "bank_phone_number": "123-456-1234",

tests/test_request.py

@@ -1,6 +1,6 @@
 import unittest
 
-from minfraud.request import maybe_hash_email
+from minfraud.request import maybe_hash_email, clean_credit_card
 
 
 class TestRequest(unittest.TestCase):
@@ -146,3 +146,83 @@ def test_maybe_hash_email(self):
                 maybe_hash_email(transaction)
 
                 self.assertEqual(test["expected"], transaction)
+
+    def test_clean_credit_card(self):
+        tests = [
+            {
+                "name": "deprecated last_4_digits is cleaned to last_digits",
+                "input": {
+                    "credit_card": {
+                        "issuer_id_number": "123456",
+                        "last_4_digits": "1234",
+                    },
+                    "device": {"ip_address": "1.1.1.1"},
+                },
+                "expected": {
+                    "credit_card": {
+                        "issuer_id_number": "123456",
+                        "last_digits": "1234",
+                    },
+                    "device": {"ip_address": "1.1.1.1"},
+                },
+            },
+            {
+                "name": "6 digit iin, 4 digit last_digits",
+                "input": {
+                    "credit_card": {
+                        "issuer_id_number": "123456",
+                        "last_digits": "1234",
+                    },
+                    "device": {"ip_address": "1.1.1.1"},
+                },
+                "expected": {
+                    "credit_card": {
+                        "issuer_id_number": "123456",
+                        "last_digits": "1234",
+                    },
+                    "device": {"ip_address": "1.1.1.1"},
+                },
+            },
+            {
+                "name": "8 digit iin, 2 digit last_digits",
+                "input": {
+                    "credit_card": {
+                        "issuer_id_number": "12345678",
+                        "last_digits": "34",
+                    },
+                    "device": {"ip_address": "1.1.1.1"},
+                },
+                "expected": {
+                    "credit_card": {
+                        "issuer_id_number": "12345678",
+                        "last_digits": "34",
+                    },
+                    "device": {"ip_address": "1.1.1.1"},
+                },
+            },
+            {
+                "name": "8 digit iin, 4 digit last_digits",
+                "input": {
+                    "credit_card": {
+                        "issuer_id_number": "12345678",
+                        "last_digits": "1234",
+                    },
+                    "device": {"ip_address": "1.1.1.1"},
+                },
+                "expected": {
+                    "credit_card": {
+                        "issuer_id_number": "12345678",
+                        "last_digits": "1234",
+                    },
+                    "device": {"ip_address": "1.1.1.1"},
+                },
+            },
+        ]
+
+        for test in tests:
+            with self.subTest(test["name"]):
+                transaction = test["input"]
+
+                clean_credit_card(transaction)
+
+                self.assertEqual(test["expected"], transaction)

tests/test_validation.py

@@ -143,16 +143,34 @@ def test_delivery_speed(self):
 
 class TestCreditCard(ValidationBase, unittest.TestCase):
     def test_issuer_id_number(self):
-        for iin in ("123456", "532313"):
+        for iin in ("123456", "532313", "88888888"):
             self.check_transaction({"credit_card": {"issuer_id_number": iin}})
         for invalid in ("12345", "1234567", 123456, "12345a"):
             self.check_invalid_transaction(
                 {"credit_card": {"issuer_id_number": invalid}}
             )
 
+    def test_last_digits(self):
+        for last_digits in ("1234", "9323", "34"):
+            self.check_transaction({"credit_card": {"last_digits": last_digits}})
+        for invalid in ("12345", "123", 1234, "123a"):
+            self.check_invalid_transaction({"credit_card": {"last_digits": invalid}})
+        self.check_transaction(
+            {"credit_card": {"issuer_id_number": "88888888", "last_digits": "12"}}
+        )
+        self.check_invalid_transaction(
+            {"credit_card": {"issuer_id_number": "88888888", "last_digits": "1234"}}
+        )
+        self.check_transaction(
+            {"credit_card": {"issuer_id_number": "666666", "last_digits": "1234"}}
+        )
+        self.check_transaction(
+            {"credit_card": {"issuer_id_number": "666666", "last_digits": "34"}}
+        )
+
     def test_last_4_digits(self):
-        for iin in ("1234", "9323"):
-            self.check_transaction({"credit_card": {"last_4_digits": iin}})
+        for last_digits in ("1234", "9323", "34"):
+            self.check_transaction({"credit_card": {"last_4_digits": last_digits}})
         for invalid in ("12345", "123", 1234, "123a"):
             self.check_invalid_transaction({"credit_card": {"last_4_digits": invalid}})