From 940db95d1bd7ae31da62b0c32a731d0f88c1a1b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Armando=20Rodr=C3=ADguez?=
 <127134616+armando-rodriguez-cko@users.noreply.github.com>
Date: Mon, 17 Aug 2026 16:59:31 +0200
Subject: [PATCH] feat(accounts): add InstrumentDocumentType with
 bank_statement

Reported internally: a merchant creating a bank_account payment instrument found no
constant for the document type. Verified in the spec, where
PlatformsPaymentInstrumentBankAccount.document.type is a single-value enum accepting
only bank_statement, which is also its default.

Kept separate from DocumentType rather than added to it. DocumentType lists identity
documents, and the API models the bank account document type as its own enum, so
putting bank_statement there would offer it where the API rejects it and imply a
passport is valid on a bank account document. DocumentType now says so in its
docstring.

One test asserts bank_statement is NOT in DocumentType. That is the one that matters
long term: it is what stops the two being merged the next time someone reports the
value as missing from the identity enum.

Refs INT-1691.
---
 checkout_sdk/common/enums.py                  |  9 +++++++++
 .../accounts/instrument_document_type_test.py | 19 +++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 tests/accounts/instrument_document_type_test.py

diff --git a/checkout_sdk/common/enums.py b/checkout_sdk/common/enums.py
index 025dd12..b3b96af 100644
--- a/checkout_sdk/common/enums.py
+++ b/checkout_sdk/common/enums.py
@@ -550,6 +550,8 @@ class AccountHolderIdentificationType(str, Enum):
 
 
 class DocumentType(str, Enum):
+    """Identity documents. The document type accepted when verifying a bank account is a
+    separate enum, InstrumentDocumentType, because the API keeps the two apart."""
     PASSPORT = 'passport'
     NATIONAL_IDENTITY_CARD = 'national_identity_card'
     DRIVING_LICENSE = 'driving_license'
@@ -558,6 +560,13 @@ class DocumentType(str, Enum):
     ELECTORAL_ID = 'electoral_id'
 
 
+class InstrumentDocumentType(str, Enum):
+    """The document type accepted by the legal document that verifies a bank account when
+    creating a payment instrument. The API accepts only bank_statement here, which is also the
+    default, and rejects the identity document types in DocumentType."""
+    BANK_STATEMENT = 'bank_statement'
+
+
 class AccountChangeIndicatorType(str, Enum):
     THIS_TRANSACTION = "this_transaction"
     LESS_THAN_THIRTY_DAYS = "less_than_thirty_days"
diff --git a/tests/accounts/instrument_document_type_test.py b/tests/accounts/instrument_document_type_test.py
new file mode 100644
index 0000000..05cea4e
--- /dev/null
+++ b/tests/accounts/instrument_document_type_test.py
@@ -0,0 +1,19 @@
+from checkout_sdk.common.enums import DocumentType, InstrumentDocumentType
+
+
+def test_should_expose_bank_statement_for_instrument_documents():
+    assert InstrumentDocumentType.BANK_STATEMENT == 'bank_statement'
+    assert InstrumentDocumentType.BANK_STATEMENT.value == 'bank_statement'
+
+
+def test_should_be_the_only_accepted_instrument_document_type():
+    # The spec declares a single-value enum here, so anything else is a caller error rather
+    # than a value we forgot to add.
+    assert [d.value for d in InstrumentDocumentType] == ['bank_statement']
+
+
+def test_should_keep_bank_statement_out_of_the_identity_document_type():
+    # bank_statement belongs to the instrument document enum, not the identity one. The API
+    # keeps them separate, and this is what stops the two being merged the next time someone
+    # reports the value as missing from DocumentType.
+    assert 'bank_statement' not in [d.value for d in DocumentType]