BILL-5584: Add descriptor_code support to bank account verification

Stripe updated microdeposit verification from two amounts to a single
6-character descriptor code. This adds support for the new path while
keeping the existing amounts path fully backwards compatible.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kevinpjones

lob_python/model/bank_account.py

@@ -124,6 +124,7 @@ def openapi_types():
             'bank_name': (str, type(None)),  # noqa: E501
             'verified': (bool, type(None)),  # noqa: E501
             'deleted': (bool, type(None)),  # noqa: E501
+            'microdeposit_type': (str, type(None)),  # noqa: E501
         }
 
     @cached_property
@@ -146,6 +147,7 @@ def discriminator():
         'bank_name': 'bank_name',  # noqa: E501
         'verified': 'verified',  # noqa: E501
         'deleted': 'deleted',  # noqa: E501
+        'microdeposit_type': 'microdeposit_type',  # noqa: E501
     }
 
     read_only_vars = {

lob_python/model/bank_account_verify.py

@@ -14,6 +14,7 @@
 
 from lob_python.model_utils import (  # noqa: F401
     ApiTypeError,
+    ApiValueError,
     ModelComposed,
     ModelNormal,
     ModelSimple,
@@ -65,6 +66,11 @@ class BankAccountVerify(ModelNormal):
             'max_items': 2,
             'min_items': 2,
         },
+        ('descriptor_code',): {
+            'regex': {
+                'pattern': r'^SM[a-zA-Z0-9]{4}$',
+            },
+        },
     }
 
     @cached_property
@@ -89,6 +95,7 @@ def openapi_types():
         """
         return {
             'amounts': (list,),  # noqa: E501
+            'descriptor_code': (str,),  # noqa: E501
         }
 
     @cached_property
@@ -98,6 +105,7 @@ def discriminator():
 
     attribute_map = {
         'amounts': 'amounts',  # noqa: E501
+        'descriptor_code': 'descriptor_code',  # noqa: E501
     }
 
     read_only_vars = {
@@ -107,13 +115,12 @@ def discriminator():
 
     @classmethod
     @convert_js_args_to_python_args
-    def _from_openapi_data(cls, amounts, *args, **kwargs):  # noqa: E501
+    def _from_openapi_data(cls, *args, **kwargs):  # noqa: E501
         """BankAccountVerify - a model defined in OpenAPI
 
-        Args:
-            amounts (list): In live mode, an array containing the two micro deposits (in cents) placed in the bank account. In test mode, no micro deposits will be placed, so any two integers between `1` and `100` will work.
-
         Keyword Args:
+            amounts (list): In live mode, an array containing the two micro deposits (in cents) placed in the bank account. In test mode, no micro deposits will be placed, so any two integers between `1` and `100` will work. [optional]  # noqa: E501
+            descriptor_code (str): The 6-character code (beginning with SM) from the bank statement descriptor of the single $0.01 microdeposit. Required when microdeposit_type is descriptor_code. [optional]  # noqa: E501
             _check_type (bool): if True, values for parameters in openapi_types
                                 will be type checked and a TypeError will be
                                 raised if the wrong type is input.
@@ -171,7 +178,6 @@ def _from_openapi_data(cls, amounts, *args, **kwargs):  # noqa: E501
         self._configuration = _configuration
         self._visited_composed_classes = _visited_composed_classes + (self.__class__,)
 
-        self.amounts = amounts
         for var_name, var_value in kwargs.items():
             if var_name not in self.attribute_map and \
                         self._configuration is not None and \
@@ -192,13 +198,12 @@ def _from_openapi_data(cls, amounts, *args, **kwargs):  # noqa: E501
     ])
 
     @convert_js_args_to_python_args
-    def __init__(self, amounts, *args, **kwargs):  # noqa: E501
+    def __init__(self, *args, **kwargs):  # noqa: E501
         """BankAccountVerify - a model defined in OpenAPI
 
-        Args:
-            amounts ([Cents]): In live mode, an array containing the two micro deposits (in cents) placed in the bank account. In test mode, no micro deposits will be placed, so any two integers between `1` and `100` will work.
-
         Keyword Args:
+            amounts ([Cents]): In live mode, an array containing the two micro deposits (in cents) placed in the bank account. In test mode, no micro deposits will be placed, so any two integers between `1` and `100` will work. [optional]  # noqa: E501
+            descriptor_code (str): The 6-character code (beginning with SM) from the bank statement descriptor of the single $0.01 microdeposit. Required when microdeposit_type is descriptor_code. [optional]  # noqa: E501
             _check_type (bool): if True, values for parameters in openapi_types
                                 will be type checked and a TypeError will be
                                 raised if the wrong type is input.
@@ -254,7 +259,18 @@ def __init__(self, amounts, *args, **kwargs):  # noqa: E501
         self._configuration = _configuration
         self._visited_composed_classes = _visited_composed_classes + (self.__class__,)
 
-        self.amounts = amounts
+        has_amounts = 'amounts' in kwargs
+        has_descriptor_code = 'descriptor_code' in kwargs
+
+        if not has_amounts and not has_descriptor_code:
+            raise ApiValueError(
+                "one of `amounts` or `descriptor_code` must be provided"
+            )
+        if has_amounts and has_descriptor_code:
+            raise ApiValueError(
+                "only one of `amounts` or `descriptor_code` may be provided"
+            )
+
         for var_name, var_value in kwargs.items():
             if var_name not in self.attribute_map and \
                         self._configuration is not None and \

test/Integration/test_bank_accounts_api.py

@@ -271,6 +271,21 @@ def test_delete404(self):
             self.api.delete("bank_fake")
         self.assertTrue("bank account not found" in context.exception.__str__())
 
+    def test_verify_with_descriptor_code200(self):
+        """Test case for verify using descriptor_code path"""
+        bank_verify = BankAccountVerify(descriptor_code="SM11AA")
+        created_bank = self.api.create(self.bank_writable)
+        verified_bank_acc = self.api.verify(created_bank.id, bank_verify)
+        self.bank_ids.append(verified_bank_acc.id)
+        self.assertIsNotNone(verified_bank_acc.id)
+
+    def test_bank_account_has_microdeposit_type(self):
+        """Test that a freshly created bank account exposes microdeposit_type"""
+        created_bank = self.api.create(self.bank_writable)
+        retrieved_bank = self.api.get(created_bank.id)
+        self.bank_ids.append(created_bank.id)
+        self.assertIn(retrieved_bank.microdeposit_type, ["amounts", "descriptor_code", None])
+
 
 if __name__ == '__main__':
     unittest.main()

test/Unit/test_bank_accounts_api.py

@@ -15,13 +15,15 @@
 
 import lob_python
 import os
+from lob_python.model.bank_account import BankAccount
 from lob_python.model.bank_account_verify import BankAccountVerify
 from lob_python.model.bank_type_enum import BankTypeEnum
 from lob_python.api.bank_accounts_api import BankAccountsApi  # noqa: E501
 from lob_python.model.bank_account_writable import BankAccountWritable  # noqa: E501
 from lob_python.model.metadata_model import MetadataModel
 from lob_python.model.include_model import IncludeModel
 from lob_python.exceptions import UnauthorizedException, NotFoundException, ApiException
+from lob_python.model_utils import ApiValueError
 from unittest.mock import Mock, MagicMock
 
 class TestBankAccountsApi(unittest.TestCase):
@@ -42,9 +44,7 @@ def setUp(self):
             signatory = "fake signatory",
         )
 
-        self.bank_account_verify = BankAccountVerify(
-          amounts = [1, 2]
-        )
+        self.bank_account_verify = BankAccountVerify(amounts=[1, 2])
 
         self.mock_list_of_bank_accounts =  MagicMock(return_value={
             "data": [{ "id": "fake 1" }, { "id": "fake 2" }]
@@ -217,5 +217,66 @@ def test_bank_account_delete_error_handle(self):
             self.mock_api.bank_account_delete("bank_fakeId")
         self.assertTrue("Not Found" in context.exception.__str__())
 
+    def test_bank_account_verify_with_descriptor_code(self):
+        """Test case for creating BankAccountVerify with descriptor_code"""
+        verify = BankAccountVerify(descriptor_code="SM11AA")
+        self.assertIsNotNone(verify)
+
+    def test_bank_account_verify_fails_with_both_amounts_and_descriptor_code(self):
+        """Test that providing both amounts and descriptor_code raises ApiValueError"""
+        with self.assertRaises(ApiValueError) as context:
+            BankAccountVerify(amounts=[1, 2], descriptor_code="SM11AA")
+        self.assertIn("only one of", str(context.exception))
+
+    def test_bank_account_verify_fails_with_neither(self):
+        """Test that providing neither amounts nor descriptor_code raises ApiValueError"""
+        with self.assertRaises(ApiValueError) as context:
+            BankAccountVerify()
+        self.assertIn("one of `amounts` or `descriptor_code` must be provided", str(context.exception))
+
+    def test_bank_account_verify_fails_with_invalid_descriptor_code_pattern(self):
+        """Test that an invalid descriptor_code pattern raises a validation error"""
+        with self.assertRaises(Exception):
+            BankAccountVerify(descriptor_code="INVALID")
+
+    def test_bank_account_has_microdeposit_type(self):
+        """Test that BankAccount accepts and returns microdeposit_type"""
+        import datetime
+        account = BankAccount(
+            routing_number="322271627",
+            account_number="123456789",
+            account_type="individual",
+            signatory="Test User",
+            id="bank_fakeId",
+            date_created=datetime.datetime.now(),
+            date_modified=datetime.datetime.now(),
+            microdeposit_type="amounts",
+        )
+        self.assertEqual(account.microdeposit_type, "amounts")
+
+        account2 = BankAccount(
+            routing_number="322271627",
+            account_number="123456789",
+            account_type="individual",
+            signatory="Test User",
+            id="bank_fakeId2",
+            date_created=datetime.datetime.now(),
+            date_modified=datetime.datetime.now(),
+            microdeposit_type="descriptor_code",
+        )
+        self.assertEqual(account2.microdeposit_type, "descriptor_code")
+
+        account3 = BankAccount(
+            routing_number="322271627",
+            account_number="123456789",
+            account_type="individual",
+            signatory="Test User",
+            id="bank_fakeId3",
+            date_created=datetime.datetime.now(),
+            date_modified=datetime.datetime.now(),
+        )
+        self.assertFalse(hasattr(account3, 'microdeposit_type') and account3.microdeposit_type is not None)
+
+
 if __name__ == '__main__':
     unittest.main()