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

api/blueprints/finstitutions/payments/callback.py

@@ -113,14 +113,14 @@ def init(blueprint_setup_state):
 # ---------------------------------------------------------------------------------------------------------------------
 
 
-@pg_callback_bp.route("/callback/<payment_id>", methods = ["POST"])
+@pg_callback_bp.route("/callback/safaricom/mpesaexpress", methods = ["POST"])
 @set_api_version(api_version = "1.0.0")
 @read_input(sanitize_headers = False, sanitize_data = False)
 @log_request_to_mongo(
     attr_name = "logs_mongo",
     project = constants.PROJECT_NAME,
     log_type = constants.MODULE_NAME,
-    operation = "pgClbkApi",
+    operation = "pgSafaricomMPesaExpressClbkApi",
     log_input = True,
     log_output = True,
     sensitive_keys = None
@@ -128,8 +128,7 @@ def init(blueprint_setup_state):
 @log_chain_to_mongo(attr_name = "logs_mongo")
 @should_not_be_under_maintenance(attr_name = "is_under_maintenance")
 @handle_cancelled_request()
-async def payment_event_callback(
-        payment_id: str = None,
+async def safaricom_m_pesa_express_callback(
         inbound_headers: dict = None,
         inbound_data: dict = None,
         inbound_files: dict = None,
@@ -138,7 +137,6 @@ async def payment_event_callback(
 
     """
     We receive payment updates for various payment gateways here.
-    :param payment_id: The id of the document in MongoDB that holds the reference to the payment.
     :param inbound_headers: auto-extracted by the decorators.
     :param inbound_data: auto-extracted by the decorators.
     :param inbound_files: auto-extracted by the decorators.
@@ -146,28 +144,80 @@ async def payment_event_callback(
     :return: A standard response structure.
     """
 
-    # ┏┓     ┏┓              ┳  ┏
-    # ┃┓┏┓╋  ┃┃┏┓┓┏┏┳┓┏┓┏┓╋  ┃┏┓╋┏┓
-    # ┗┛┗ ┗  ┣┛┗┻┗┫┛┗┗┗ ┛┗┗  ┻┛┗┛┗┛
-    #             ┛
-
     # payment_info = await current_app.payment_controller.get_payment_internal(
     #     mongo_conn = current_app.data_mongo,
     #     payment_id = ObjectId(payment_id)
     # )
     # print("PAYMENT INFO:", json.to_string(payment_info.model_dump(), default=str))
 
+    # ┏┓ ┓ ┓  ┏┓
+    # ┣┫┏┫┏┫  ┣ ┓┏┏┓┏┓╋
+    # ┛┗┗┻┗┻  ┗┛┗┛┗ ┛┗┗
+
+    # Map out the documented codes provided by the payment gateway.
+    # URL: https://developer.safaricom.co.ke/APIs/MpesaExpressSimulate
+    code_map = {
+        0: {
+            "status": "settled",
+            "message": "Payment successful :)"
+        },  # ... Success
+        1037: {
+            "status": "failed",
+            "message": "The payment gateway could not reach your customer."
+        },  # ... DS Timeout. User could not be reached.
+        1025: {
+            "status": "failed",
+            "message": "There was a system error in the payment gateway (1025)."
+        },  # ... System error while trying to send the push request.
+        9999: {
+            "status": "failed",
+            "message": "There was a system error in the payment gateway (9999)."
+        },  # ... System error while trying to send the push request.
+        1032: {
+            "status": "rejected",
+            "message": "Your customer declined the payment request."
+        },  # ... Request Cancelled by the user.
+        1: {
+            "status": "failed",
+            "message": "Your customer has insufficient balance."
+        },  # ... The user has insufficient balance.
+        2001: {
+            "status": "failed",
+            "message": "The payment gateway says your credentials are invalid."
+        },  # ... Invalid credentials of the initiator.
+        1019: {
+            "status": "failed",
+            "message": "The transaction expired before your customer processed it."
+        },  # ... Transaction expired.
+        1001: {
+            "status": "failed",
+            "message": "Your customer is already in the middle of some transaction on the payment gateway."
+        },  # ... The payer is already making some transaction.
+    }
+
+    # Figure out which of the above codes is relevant to you:
+    pg_reference_id = inbound_data["Body"]["stkCallback"]["CheckoutRequestID"]
+    pg_result_code = int(inbound_data["Body"]["stkCallback"]["ResultCode"])
+    relevant_code = code_map.get(
+        pg_result_code,
+        {
+            "status": "unknown",
+            "message": f"Unknown code '{pg_result_code}' from the payment gateway."
+        }
+    )
+
     # For now, we just insert the event into the record:
-    event_note_success = await current_app.payment_controller.add_event(
+    event_note_success = await current_app.payment_controller.add_event_by_client_reference_id(
         mongo_conn = current_app.data_mongo,
-        payment_id = ObjectId(payment_id),
         event = PaymentEvent(
-            paymentStatus = "unknown",
+            paymentStatus = relevant_code["status"],
+            message = relevant_code["message"],
             initByPG = True,
             httpCode = None,
             headers = inbound_headers,
             payload = inbound_data
-        )
+        ),
+        client_reference_id = pg_reference_id
     )
 
     # ┳┓
@@ -178,7 +228,7 @@ async def payment_event_callback(
     # Done here:
     return ResponseModel(
         status_code = StatusCodes.OK if event_note_success else StatusCodes.FAILED,
-        http_code = HttpCodes.NOT_IMPLEMENTED
+        http_code = HttpCodes.SUCCESS if event_note_success else HttpCodes.INTERNAL_SERVER_ERROR
     )