(20241216) Payments requesting started, callback noting started.

models/api/finstitutions/payments/request.py

@@ -110,17 +110,6 @@ class PGPaymentRequestHeaders(BaseModel):
 
 class PGPaymentRequestData(BaseModel):
 
-    # {
-    #     "customerMobileNumber": "",
-    #     "tokenId": "",
-    #     "description": "",
-    #     "payerNumber": "",
-    #     "amount": "",
-    #     "currency": "",
-    #     "emailAddress": "",
-    #     "reference": "",
-    # }
-
     tokenKey: ObjectId = Field(
         description = "the auth token to use to send this message",
         frozen = True,
@@ -164,6 +153,16 @@ class PGPaymentRequestData(BaseModel):
         examples = ["INR", "USD", "KES"]
     )
 
+    reference: str = Field(
+        description = "some reference against which the payment was made",
+        frozen = True
+    )
+
+    description: str = Field(
+        description = "a short, human-readable description of the payment",
+        frozen = True
+    )
+
     metadata: dict = Field(
         description = "any extra information about this payment",
         frozen = True
@@ -210,11 +209,6 @@ class PaymentRequestOneResult(BaseModel):
         default = None
     )
 
-    paymentDetails: CorePaymentModel = Field(
-        description = "the actual data of the payment",
-        default = None
-    )
-
     # ┏┓    ┏•
     # ┃ ┏┓┏┓╋┓┏┓
     # ┗┛┗┛┛┗┛┗┗┫

models/core/payment.py

@@ -138,17 +138,20 @@ class PaymentEvent(BaseModel):
 
     eventTs: AwareDatetime = Field(
         description = "to know the date and time (utc) of this update",
-        frozen = True
+        frozen = True,
+        default_factory = lambda: date_time.get_current_utc_date_time(as_string = False)
     )
 
     paymentStatus: Literal[
-        "initFailed",  # ... When we tried to initiate the request, but the payment gateway (PG) rejected it.
+        "queued",  # ....... When the UI sends a payment request, but the payment gateway (PG) hasn't received it yet.
+        "initFailed",  # ... When we tried to initiate the request, but the PG rejected it.
         "initiated",  # .... When we made a successful payment request, or the customer initiated one from the PG.
         "failed",  # ....... When the customer tried paying, but it failed (e.g.: because of an incorrect pin).
         "rejected",  # ..... When the customer explicitly rejected the payment.
         "authorized",  # ... When the customer made the payment (but it hasn't been settled in your account yet).
         "settled",  # ...... When the PG sends the money to your account.
         "refunded",  # ..... When the money was refunded to the client.
+        "unknown"  # ....... When integrating a new gateway and some specific status is not known.
     ] = Field(
         description = "the status of the payment request to see what stage of the process we are in",
         frozen = False
@@ -220,9 +223,10 @@ class CorePaymentModel(BaseModel):
         default_factory = lambda: date_time.get_current_utc_date_time(as_string = False)
     )
 
-    lastEventTs: AwareDatetime = Field(
+    lastEventTs: AwareDatetime | None = Field(
         description = "the time (utc) at which the last event occurred",
-        frozen = True
+        frozen = True,
+        default = None
     )
 
     lastPaymentStatus: str = Field(
@@ -263,7 +267,7 @@ class CorePaymentModel(BaseModel):
         frozen = True
     )
 
-    clientPaymentReferenceId: int | str = Field(
+    clientPaymentReferenceId: int | str | None = Field(
         description = "the reference id given by the third-party client",
         frozen = False,
         default = None
@@ -271,7 +275,8 @@ class CorePaymentModel(BaseModel):
 
     events: List[PaymentEvent] = Field(
         description = "an array of all the events that happened in the process of this payment",
-        frozen = False
+        frozen = False,
+        default = []
     )
 
     # ┏┓    ┏•
@@ -296,6 +301,7 @@ class CorePaymentModel(BaseModel):
         payment_json = {
             "paymentId": str(self.messageId),
             "user": self.user,
+            "customer": self.customer,
             "ts": self.ts.isoformat(),
             "lastEventTs": self.lastEventTs,
             "lastPaymentStatus": self.lastPaymentStatus,
@@ -320,6 +326,7 @@ class CorePaymentModel(BaseModel):
         return {
             "paymentId": str(self.messageId),
             "user": self.user,
+            "customer": self.customer,
             "ts": self.ts.isoformat(),
             "lastEventTs": self.lastEventTs,
             "lastPaymentStatus": self.lastPaymentStatus,
@@ -335,7 +342,7 @@ class CorePaymentModel(BaseModel):
     # ┃┃┏┓┃┓┏┫┏┓╋┓┏┓┏┓
     # ┗┛┗┻┗┗┗┻┗┻┗┗┗┛┛┗
 
-    @field_validator("lastEventTs", mode = "before")
+    @field_validator("ts", "lastEventTs", mode = "before")
     def parse_date_time(cls, value):
         return date_time.parse_date_time(input_value = value, timezone = date_time.TIMEZONE_UTC)