From 4367a76e3e84f344a0a7977e9b8814b30e5bc25f Mon Sep 17 00:00:00 2001
From: Alejandro Torres <jowyto@gmail.com>
Date: Tue, 6 Oct 2026 18:43:07 -0300
Subject: [PATCH] feat: add transaction status constants

Add TransactionStatus enum with the status values documented for the
Webpay Plus API (INITIALIZED, AUTHORIZED, REVERSED, FAILED, NULLIFIED,
PARTIALLY_NULLIFIED, CAPTURED). Members inherit from str, so they compare
equal to the raw values returned by commit and status, which are left
unchanged.
---
 tests/common/__init__.py                |  0
 tests/common/test_transaction_status.py | 54 +++++++++++++++++++++++++
 transbank/common/transaction_status.py  | 15 +++++++
 3 files changed, 69 insertions(+)
 create mode 100644 tests/common/__init__.py
 create mode 100644 tests/common/test_transaction_status.py
 create mode 100644 transbank/common/transaction_status.py

diff --git a/tests/common/__init__.py b/tests/common/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/common/test_transaction_status.py b/tests/common/test_transaction_status.py
new file mode 100644
index 00000000..9218a551
--- /dev/null
+++ b/tests/common/test_transaction_status.py
@@ -0,0 +1,54 @@
+import unittest
+from unittest.mock import Mock
+from unittest.mock import patch
+import json
+from transbank.common.transaction_status import TransactionStatus
+from transbank.webpay.webpay_plus.transaction import Transaction
+from tests.mocks.responses_api_mocks import responses
+from transbank.common.integration_commerce_codes import IntegrationCommerceCodes
+from transbank.common.integration_api_keys import IntegrationApiKeys
+
+
+class TransactionStatusTestCase(unittest.TestCase):
+
+    def setUp(self) -> None:
+        self.token_mock = '01abf2be20aad1da804aeae1ed3062fb8fba108ee0e07f4d37181f51c3f6714d'
+        self.mock_response = Mock()
+        self.transaction = Transaction.build_for_integration(
+            IntegrationCommerceCodes.WEBPAY_PLUS, IntegrationApiKeys.WEBPAY)
+
+    def test_values_match_documented_statuses(self):
+        documented_statuses = ['INITIALIZED', 'AUTHORIZED', 'REVERSED', 'FAILED', 'NULLIFIED',
+                               'PARTIALLY_NULLIFIED', 'CAPTURED']
+
+        self.assertEqual([status.value for status in TransactionStatus], documented_statuses)
+
+    def test_members_are_equal_to_api_strings(self):
+        for status in TransactionStatus:
+            self.assertIsInstance(status, str)
+            self.assertEqual(status, status.name)
+
+    def test_str_and_json_return_plain_value(self):
+        self.assertEqual(str(TransactionStatus.AUTHORIZED), 'AUTHORIZED')
+        self.assertEqual(json.dumps({'status': TransactionStatus.FAILED}), '{"status": "FAILED"}')
+
+    def test_build_from_api_value(self):
+        status = TransactionStatus(responses['commit_status_response']['status'])
+
+        self.assertIs(status, TransactionStatus.AUTHORIZED)
+
+    def test_unknown_value_raises_value_error(self):
+        with self.assertRaises(ValueError):
+            TransactionStatus('UNKNOWN_STATUS')
+
+    @patch('transbank.common.request_service.requests.put')
+    def test_commit_response_is_unchanged_and_comparable(self, mock_put):
+        self.mock_response.status_code = 200
+        self.mock_response.text = json.dumps(responses['commit_status_response'])
+        mock_put.return_value = self.mock_response
+
+        response = self.transaction.commit(self.token_mock)
+
+        self.assertEqual(response, responses['commit_status_response'])
+        self.assertIs(type(response['status']), str)
+        self.assertEqual(response['status'], TransactionStatus.AUTHORIZED)
diff --git a/transbank/common/transaction_status.py b/transbank/common/transaction_status.py
new file mode 100644
index 00000000..0adde607
--- /dev/null
+++ b/transbank/common/transaction_status.py
@@ -0,0 +1,15 @@
+from enum import Enum, unique
+
+
+@unique
+class TransactionStatus(str, Enum):
+    INITIALIZED = "INITIALIZED"
+    AUTHORIZED = "AUTHORIZED"
+    REVERSED = "REVERSED"
+    FAILED = "FAILED"
+    NULLIFIED = "NULLIFIED"
+    PARTIALLY_NULLIFIED = "PARTIALLY_NULLIFIED"
+    CAPTURED = "CAPTURED"
+
+    def __str__(self):
+        return self.value