(20241217) Payment callback ready for Safaricom M-Pesa Express.

controllers/core/payment.py

@@ -293,7 +293,7 @@ class CorePaymentController(BaseModel):
     # We don't support updating payments themselves,
     # but we will allow updating fields like tags, adding events, etc.
 
-    async def add_event(
+    async def add_event_by_payment_id(
             self,
             mongo_conn: AsyncMongo,
             payment_id: ObjectId | str,
@@ -332,6 +332,43 @@ class CorePaymentController(BaseModel):
             raise_exception = True
         )
 
+    async def add_event_by_client_reference_id(
+            self,
+            mongo_conn: AsyncMongo,
+            client_reference_id: str,
+            event: PaymentEvent,
+    ) -> bool:
+
+        """
+        Add an event to an existing record of a payment detail.
+        :param mongo_conn: The instance of the database connector to use for the operation.
+        :param event: The event that occurred. This will typically be generated by the third-party client.
+        :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: True if successfully noted, else False.
+        """
+
+        # Prepare the update document:
+        update_json = {
+            "$push": {
+                "events": event.model_dump()
+            },
+            "$set": {
+                "lastEventTs": date_time.get_current_ist_date_time(as_string = False),
+                "lastPaymentStatus": event.paymentStatus
+            }
+        }
+        if client_reference_id: update_json["$set"]["clientPaymentReferenceId"] = client_reference_id
+
+        # Try to update the existing record:
+        return await mongo_conn.update_one(
+            collection = self.PAYMENTS_COLLECTION,
+            filter = {"clientPaymentReferenceId": client_reference_id},
+            update = update_json,
+            upsert = False,
+            raise_exception = True
+        )
+
     async def update_tags(
             self,
             mongo_conn: AsyncMongo,