(20241228) Started making provisions for disabling payment gateway accounts when the gateway says that the credentials are invalid. Am stuck at one place, though.

controllers_v2/finstitutions/payments/base.py

@@ -47,7 +47,11 @@ from controllers_v2.core.auth_token import CoreAuthTokenController
 from models.core.user import CoreUserInfoModel
 from models.core.auth_token import CoreAuthTokenModel
 from models.core.payment import CorePaymentModel, PaymentEvent, CustomerDetails
-from models.api.finstitutions.payments.request import PGPaymentRequestData, PaymentRequestOneResult
+from models.api.finstitutions.payments.request import (
+    PGPaymentRequestData,
+    PaymentRequestOneResult,
+    PaymentCallbackResult
+)
 
 # To work with MongoDB:
 from bson import ObjectId
@@ -270,6 +274,34 @@ class PaymentsController(CoreAuthTokenController, ABC):
         # we return it as our data model:
         return CorePaymentModel(**record)
 
+    async def get_payment_by_client_reference_id(
+            self,
+            mongo_data_conn: AsyncMongo,
+            client_reference_id: str
+    ) -> CorePaymentModel | None:
+
+        """
+        Gets one payment detail if you know its payment id.
+        :param mongo_data_conn: The instance of the database connector to use for the operation.
+        :param client_reference_id: The way the client identifies this payment. You need to pass this only on the first
+            event. Typically, when you initiate the payment request.
+        :return: The contents of that one payment detail in a structured format.
+        """
+
+        # We fetch the whole payload of that one message:
+        record = await mongo_data_conn.find_one(
+            collection = self.PAYMENTS_COLLECTION,
+            filter = {"clientPaymentReferenceId": client_reference_id},
+            raise_exception = True
+        )
+
+        # If no such message was found:
+        if record is None: return None
+
+        # If a record was found,
+        # we return it as our data model:
+        return CorePaymentModel(**record)
+
     # ┳┳   ┓       ┏┓
     # ┃┃┏┓┏┫┏┓╋┏┓  ┃┃┏┓┓┏┏┳┓┏┓┏┓╋┏
     # ┗┛┣┛┗┻┗┻┗┗   ┣┛┗┻┗┫┛┗┗┗ ┛┗┗┛
@@ -466,6 +498,7 @@ class PaymentsController(CoreAuthTokenController, ABC):
     @abstractmethod
     async def request_payment(
             self,
+            sql_conn: AsyncMySQL,
             mongo_data_conn: AsyncMongo,
             auth_token: CoreAuthTokenModel,
             user_info: CoreUserInfoModel,
@@ -474,6 +507,8 @@ class PaymentsController(CoreAuthTokenController, ABC):
 
         """
         To request payment from someone through a payment gateway.
+        :param sql_conn: Only needed when a payment gateway says that the credentials are invalid and the account needs
+            to be disabled.
         :param mongo_data_conn: The database connection to use to perform this activity.
         :param auth_token: The token that has to be used to fetch the data.
         :param user_info: The info. of your user, so that you can identify who requested the payment.
@@ -486,18 +521,21 @@ class PaymentsController(CoreAuthTokenController, ABC):
     @abstractmethod
     async def handle_payment_callback(
             self,
+            sql_conn: AsyncMySQL,
             mongo_data_conn: AsyncMongo,
             inbound_data: dict,
             inbound_headers: dict
-    ) -> None:
+    ) -> PaymentCallbackResult:
 
         """
         Whenever the payment gateway sends an update about a requested payment, we use this method to update our records
         as per the specification of the third-party payment gateway.
+        :param sql_conn: Only needed when a payment gateway says that the credentials are invalid and the account needs
+            to be disabled.
         :param mongo_data_conn: The database connection to use to perform this activity.
         :param inbound_data: The data sent by the payment gateway in their update.
         :param inbound_headers: The headers sent by the payment gateway in their update.
-        :return: ??
+        :return: A structured response about the process of updating the payment event.
         """
 
         pass