mpesakit 0.1.2__py3-none-any.whl

mpesakit/B2B_express_checkout/B2B_express_checkout.py

@@ -0,0 +1,51 @@
+"""B2BExpressCheckout: Handles M-Pesa B2B Express Checkout API interactions.
+
+This module provides functionality to initiate a B2B Express Checkout USSD Push transaction and handle result/timeout notifications
+using the M-Pesa API. Requires a valid access token for authentication and uses the HttpClient for HTTP requests.
+"""
+
+from pydantic import BaseModel, ConfigDict
+from mpesakit.auth import TokenManager
+from mpesakit.http_client import HttpClient
+
+from .schemas import (
+    B2BExpressCheckoutRequest,
+    B2BExpressCheckoutResponse,
+)
+
+
+class B2BExpressCheckout(BaseModel):
+    """Represents the B2B Express Checkout API client for M-Pesa operations.
+
+    https://developer.safaricom.co.ke/APIs/B2BExpressCheckout
+
+    Attributes:
+        http_client (HttpClient): HTTP client for making requests to the M-Pesa API.
+        token_manager (TokenManager): Manages access tokens for authentication.
+    """
+
+    http_client: HttpClient
+    token_manager: TokenManager
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def ussd_push(
+        self, request: B2BExpressCheckoutRequest
+    ) -> B2BExpressCheckoutResponse:
+        """Initiates a B2B Express Checkout USSD Push transaction.
+
+        Args:
+            request (B2BExpressCheckoutRequest): The B2B Express Checkout request data.
+
+        Returns:
+            B2BExpressCheckoutResponse: Response from the M-Pesa API.
+        """
+        url = "/v1/ussdpush/get-msisdn"
+        headers = {
+            "Authorization": f"Bearer {self.token_manager.get_token()}",
+            "Content-Type": "application/json",
+        }
+        response_data = self.http_client.post(
+            url, json=request.model_dump(mode="json"), headers=headers
+        )
+        return B2BExpressCheckoutResponse(**response_data)

mpesakit/B2B_express_checkout/__init__.py

@@ -0,0 +1,16 @@
+from .schemas import (
+    B2BExpressCheckoutRequest,
+    B2BExpressCheckoutResponse,
+    B2BExpressCheckoutCallback,
+    B2BExpressCallbackResponse,
+)
+
+from .B2B_express_checkout import B2BExpressCheckout
+
+__all__ = [
+    "B2BExpressCheckout",
+    "B2BExpressCheckoutRequest",
+    "B2BExpressCheckoutResponse",
+    "B2BExpressCheckoutCallback",
+    "B2BExpressCallbackResponse",
+]

mpesakit/B2B_express_checkout/schemas.py

@@ -0,0 +1,127 @@
+"""Schemas for M-PESA B2B Express Checkout APIs."""
+
+from pydantic import BaseModel, Field, ConfigDict, HttpUrl
+from typing import Optional
+
+
+class B2BExpressCheckoutRequest(BaseModel):
+    """Request schema for B2B Express Checkout USSD Push."""
+
+    primaryShortCode: int = Field(
+        ..., description="Merchant's till (debit party) shortcode/tillNumber."
+    )
+    receiverShortCode: int = Field(
+        ..., description="Vendor's paybill (credit party) shortcode."
+    )
+    amount: int = Field(..., description="Amount to be sent to vendor.")
+    paymentRef: str = Field(
+        ..., description="Reference for the payment (appears in text for merchant)."
+    )
+    callbackUrl: HttpUrl = Field(
+        ..., description="Vendor system endpoint for confirmation response."
+    )
+    partnerName: str = Field(..., description="Vendor's organization friendly name.")
+    RequestRefID: str = Field(..., description="Unique identifier for each request.")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "primaryShortCode": 123456,
+                "receiverShortCode": 654321,
+                "amount": 100,
+                "paymentRef": "Invoice123",
+                "callbackUrl": "http://example.com/result",
+                "partnerName": "VendorName",
+                "RequestRefID": "550e8400-e29b-41d4-a716-446655440000",
+            }
+        }
+    )
+
+
+class B2BExpressCheckoutResponse(BaseModel):
+    """Acknowledgment response schema for B2B Express Checkout USSD Push."""
+
+    code: str = Field(
+        ..., description="Shows if the push was successful (0) or failed."
+    )
+    status: str = Field(..., description="USSD initiation status message.")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "code": "0",
+                "status": "USSD Initiated Successfully",
+            }
+        }
+    )
+
+    def is_successful(self) -> bool:
+        """Check if the response indicates a successful USSD initiation."""
+        return self.code == "0"
+
+
+class B2BExpressCheckoutCallback(BaseModel):
+    """Callback response schema for B2B Express Checkout USSD Push."""
+
+    resultCode: str = Field(
+        ..., description="Status code: 0=success, other=fail/cancelled."
+    )
+    resultDesc: str = Field(..., description="Description of transaction result.")
+    amount: Optional[float] = Field(None, description="Amount initiated for payment.")
+    requestId: str = Field(..., description="Unique identifier of the request.")
+    paymentReference: Optional[str] = Field(
+        None, description="Reference for the payment."
+    )
+    resultType: Optional[str] = Field(
+        None, description="Status code for transaction sent to listener."
+    )
+    conversationID: Optional[str] = Field(
+        None, description="Global unique transaction request ID from M-Pesa."
+    )
+    transactionId: Optional[str] = Field(
+        None, description="Mpesa Receipt No of the transaction."
+    )
+    status: Optional[str] = Field(
+        None, description="Transaction status (SUCCESS/FAILED)."
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "resultCode": "0",
+                "resultDesc": "The service request is processed successfully.",
+                "amount": "71.0",
+                "requestId": "404e1aec-19e0-4ce3-973d-bd92e94c8021",
+                "resultType": "0",
+                "conversationID": "AG_20230426_2010434680d9f5a73766",
+                "transactionId": "RDQ01NFT1Q",
+                "status": "SUCCESS",
+            }
+        }
+    )
+
+    def is_successful(self) -> bool:
+        """Check if the callback indicates a successful transaction."""
+        return self.resultCode == "0"
+
+
+class B2BExpressCallbackResponse(BaseModel):
+    """Response schema for B2B Express Checkout callback."""
+
+    ResultCode: int = Field(
+        default=0,
+        description="Result code (0=Success, other=Failure).",
+    )
+    ResultDesc: str = Field(
+        default="Callback received successfully.",
+        description="Result description.",
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "ResultCode": 0,
+                "ResultDesc": "Callback received successfully.",
+            }
+        }
+    )

mpesakit/B2C/B2C.py

@@ -0,0 +1,47 @@
+"""B2C: Handles M-Pesa B2C (Business to Customer) API interactions.
+
+This module provides functionality to initiate B2C payments using the M-Pesa API.
+Requires a valid access token for authentication and uses the HttpClient for HTTP requests.
+"""
+
+from pydantic import BaseModel, ConfigDict
+from mpesakit.auth import TokenManager
+from mpesakit.http_client import HttpClient
+
+from .schemas import (
+    B2CRequest,
+    B2CResponse,
+)
+
+
+class B2C(BaseModel):
+    """Represents the B2C API client for M-Pesa Business to Customer operations.
+
+    https://developer.safaricom.co.ke/APIs/BusinessToCustomerPayment
+
+    Attributes:
+        http_client (HttpClient): HTTP client for making requests to the M-Pesa API.
+        token_manager (TokenManager): Manages access tokens for authentication.
+    """
+
+    http_client: HttpClient
+    token_manager: TokenManager
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def send_payment(self, request: B2CRequest) -> B2CResponse:
+        """Initiates a B2C payment request.
+
+        Args:
+            request (B2CRequest): The payment request details.
+
+        Returns:
+            B2CResponse: Response from the M-Pesa API after payment initiation.
+        """
+        url = "/mpesa/b2c/v3/paymentrequest"
+        headers = {
+            "Authorization": f"Bearer {self.token_manager.get_token()}",
+            "Content-Type": "application/json",
+        }
+        response_data = self.http_client.post(url, json=dict(request), headers=headers)
+        return B2CResponse(**response_data)

mpesakit/B2C/__init__.py

@@ -0,0 +1,23 @@
+from .schemas import (
+    B2CCommandIDType,
+    B2CRequest,
+    B2CResponse,
+    B2CResultParameter,
+    B2CResultMetadata,
+    B2CResultCallback,
+    B2CTimeoutCallback,
+    B2CTimeoutCallbackResponse,
+)
+from .B2C import B2C
+
+__all__ = [
+    "B2C",
+    "B2CCommandIDType",
+    "B2CRequest",
+    "B2CResponse",
+    "B2CResultParameter",
+    "B2CResultMetadata",
+    "B2CResultCallback",
+    "B2CTimeoutCallbackResponse",
+    "B2CTimeoutCallback",
+]

mpesakit/B2C/schemas.py

@@ -0,0 +1,339 @@
+"""This module defines schemas for M-Pesa B2C API requests and responses.
+
+It includes models for payment requests, responses, and result notifications.
+"""
+
+from enum import Enum
+from pydantic import BaseModel, Field, ConfigDict, model_validator
+from typing import Optional
+from mpesakit.utils.phone import normalize_phone_number
+
+
+class B2CCommandIDType(str, Enum):
+    """Allowed values for CommandID in B2C payment requests."""
+
+    SalaryPayment = "SalaryPayment"  # Both Registeren and Unregistered M-Pesa users
+    BusinessPayment = "BusinessPayment"  # Only for registered M-Pesa users
+    PromotionPayment = (
+        "PromotionPayment"  # Congratulatory payments for registered M-Pesa users only
+    )
+
+
+class B2CRequest(BaseModel):
+    """Request schema for B2C payment initiation.
+
+    This schema is used to initiate Business-to-Customer (B2C) payments via the Safaricom Daraja API.
+
+    NOTE: To use this API in production, you must apply for a Bulk Disbursement Account and obtain a Shortcode.
+    The Shortcode required here is NOT the same as a Buy Goods Till or Paybill Till Number.
+    For more information and to apply for a Bulk Disbursement Account, refer to the official documentation:
+    https://developer.safaricom.co.ke/APIs/BusinessToCustomerPayment
+
+    Attributes:
+        OriginatorConversationID (str): Unique identifier for the specific request.
+        InitiatorName (str): Username used to initiate the request.
+        SecurityCredential (str): Encrypted security credential.
+        CommandID (str): Type of transaction to perform. Must be a valid B2CCommandIDType.
+        Amount (int): Amount to be sent to the customer.
+        PartyA (int): Shortcode sending the funds (Bulk Disbursement Account Shortcode).
+        PartyB (int): Mobile number receiving the funds (must be a valid Kenyan phone number).
+        Remarks (str): Comments for the transaction.
+        QueueTimeOutURL (str): URL for timeout notifications.
+        ResultURL (str): URL for result notifications.
+        Occasion (Optional[str]): Optional occasion for payment.
+    """
+
+    OriginatorConversationID: str = Field(
+        ..., description="Unique identifier for the specific request."
+    )
+    InitiatorName: str = Field(
+        ..., description="Username used to initiate the request."
+    )
+    SecurityCredential: str = Field(..., description="Encrypted security credential.")
+    CommandID: str = Field(..., description="Type of transaction to perform.")
+    Amount: int = Field(..., description="Amount to be sent to customer.")
+    PartyA: int = Field(..., description="Shortcode sending the funds.")
+    PartyB: int = Field(..., description="Mobile number receiving the funds.")
+    Remarks: str = Field(..., description="Comments for the transaction.")
+    QueueTimeOutURL: str = Field(..., description="URL for timeout notifications.")
+    ResultURL: str = Field(..., description="URL for result notifications.")
+    Occasion: Optional[str] = Field(None, description="Optional occasion for payment.")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "OriginatorConversationID": "12345-67890-1",
+                "InitiatorName": "testapi",
+                "SecurityCredential": "encrypted_credential",
+                "CommandID": "BusinessPayment",
+                "Amount": 1000,
+                "PartyA": 600999,
+                "PartyB": 254712345678,
+                "Remarks": "Salary for June",
+                "QueueTimeOutURL": "https://example.com/timeout",
+                "ResultURL": "https://example.com/result",
+                "Occasion": "JuneSalary",
+            }
+        }
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate(cls, values):
+        """Validate CommandID and URLs."""
+        cls._validate_command_id(values)
+        cls._validate_partyb(values)
+        cls._validate_remarks(values)
+        cls._validate_occasion(values)
+        return values
+
+    @classmethod
+    def _validate_occasion(cls, values):
+        """Ensure Occasion is not more than 100 characters."""
+        occasion = values.get("Occasion")
+        if occasion is not None and len(occasion) > 100:
+            raise ValueError("Occasion must not exceed 100 characters.")
+        return values
+
+    @classmethod
+    def _validate_remarks(cls, values):
+        """Ensure Remarks is not more than 100 characters."""
+        remarks = values.get("Remarks")
+        if remarks is not None and len(remarks) > 100:
+            raise ValueError("Remarks must not exceed 100 characters.")
+        return values
+
+    @classmethod
+    def _validate_partyb(cls, values):
+        """Ensure PartyB is a valid Kenyan phone number."""
+        partyb = values.get("PartyB")
+        normalized = normalize_phone_number(str(partyb))
+        if normalized is None:
+            raise ValueError(
+                f"PartyB must be a valid Kenyan phone number, got '{partyb}'"
+            )
+        values["PartyB"] = int(normalized)
+        return values
+
+    @classmethod
+    def _validate_command_id(cls, values):
+        """Ensure CommandID is a valid B2CCommandIDType value."""
+        command_id = values.get("CommandID")
+        valid_ids = [e.value for e in B2CCommandIDType]
+        if command_id not in valid_ids:
+            raise ValueError(
+                f"CommandID must be one of {valid_ids}, got '{command_id}'"
+            )
+        return values
+
+
+class B2CResponse(BaseModel):
+    """Response schema for B2C payment initiation."""
+
+    ConversationID: Optional[str] = Field(
+        ..., description="Unique ID for the payment request."
+    )
+    OriginatorConversationID: Optional[str] = Field(
+        ..., description="ID for tracking the request."
+    )
+    ResponseCode: str | int = Field(..., description="Status code, 0 means success.")
+    ResponseDescription: str = Field(..., description="Status message.")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "ConversationID": "AG_20170717_00006c6f7f5b8b6b1a62",
+                "OriginatorConversationID": "12345-67890-1",
+                "ResponseCode": "0",
+                "ResponseDescription": "Accept the service request successfully.",
+            }
+        }
+    )
+
+    def is_successful(self) -> bool:
+        """Return True if ResponseCode indicates success (e.g., '0', '00000000')."""
+        code = str(self.ResponseCode)
+        return code.strip("0") == "" and code != ""
+
+
+class B2CResultParameter(BaseModel):
+    """Parameter item in B2C result notification."""
+
+    Key: str = Field(..., description="Parameter name.")
+    Value: str | int | float = Field(..., description="Parameter value.")
+
+
+class B2CResultMetadata(BaseModel):
+    """Metadata for B2C result notification."""
+
+    ResultType: int = Field(..., description="Type of result (0=Success, 1=Failure).")
+    ResultCode: int = Field(..., description="Result code (0=Success).")
+    ResultDesc: str = Field(..., description="Result description.")
+    OriginatorConversationID: str = Field(
+        ..., description="Originator conversation ID."
+    )
+    ConversationID: str = Field(..., description="Conversation ID.")
+    TransactionID: Optional[str] = Field(
+        None, description="M-Pesa transaction ID (if successful)."
+    )
+    ResultParameters: Optional[list[B2CResultParameter]] = Field(
+        None, description="List of result parameters."
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "ResultType": 0,
+                "ResultCode": 0,
+                "ResultDesc": "The service request is processed successfully.",
+                "OriginatorConversationID": "12345-67890-1",
+                "ConversationID": "AG_20170717_00006c6f7f5b8b6b1a62",
+                "TransactionID": "LKXXXX1234",
+                "ResultParameters": [
+                    {"Key": "TransactionAmount", "Value": 1000},
+                    {"Key": "TransactionReceipt", "Value": "LKXXXX1234"},
+                ],
+            }
+        }
+    )
+
+    def __init__(self, **data):
+        """Initialize B2CResultMetadata and cache parameters as a dictionary."""
+        super().__init__(**data)
+
+        self._parameters_dict = {
+            param.Key: param.Value for param in self.ResultParameters or []
+        }
+
+    @property
+    def transaction_amount(self) -> Optional[int | float]:
+        """Return the TransactionAmount value if present."""
+        return self._parameters_dict.get("TransactionAmount")
+
+    @property
+    def transaction_receipt(self) -> Optional[str]:
+        """Return the TransactionReceipt value if present."""
+        return self._parameters_dict.get("TransactionReceipt")
+
+    @property
+    def recipient_is_registered(self) -> Optional[bool]:
+        """Return True if B2CRecipientIsRegisteredCustomer is 'Y', False if 'N', None if missing."""
+        val = self._parameters_dict.get("B2CRecipientIsRegisteredCustomer")
+        if val == "Y":
+            return True
+        if val == "N":
+            return False
+        return None
+
+    @property
+    def receiver_party_public_name(self) -> Optional[str]:
+        """Return the ReceiverPartyPublicName value if present."""
+        return self._parameters_dict.get("ReceiverPartyPublicName")
+
+    @property
+    def transaction_completed_datetime(self) -> Optional[str]:
+        """Return the TransactionCompletedDateTime value if present."""
+        return self._parameters_dict.get("TransactionCompletedDateTime")
+
+    @property
+    def charges_paid_account_available_funds(self) -> Optional[float]:
+        """Return the B2CChargesPaidAccountAvailableFunds value if present."""
+        return self._parameters_dict.get("B2CChargesPaidAccountAvailableFunds")
+
+    @property
+    def utility_account_available_funds(self) -> Optional[float]:
+        """Return the B2CUtilityAccountAvailableFunds value if present."""
+        return self._parameters_dict.get("B2CUtilityAccountAvailableFunds")
+
+    @property
+    def working_account_available_funds(self) -> Optional[float]:
+        """Return the B2CWorkingAccountAvailableFunds value if present."""
+        return self._parameters_dict.get("B2CWorkingAccountAvailableFunds")
+
+
+class B2CResultCallback(BaseModel):
+    """Schema for B2C result notification sent to ResultURL."""
+
+    Result: B2CResultMetadata = Field(..., description="Result metadata.")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "Result": {
+                    "ResultType": 0,
+                    "ResultCode": 0,
+                    "ResultDesc": "The service request is processed successfully.",
+                    "OriginatorConversationID": "12345-67890-1",
+                    "ConversationID": "AG_20170717_00006c6f7f5b8b6b1a62",
+                    "TransactionID": "LKXXXX1234",
+                    "ResultParameters": [
+                        {"Key": "TransactionAmount", "Value": 1000},
+                        {"Key": "TransactionReceipt", "Value": "LKXXXX1234"},
+                    ],
+                }
+            }
+        }
+    )
+
+
+class B2CResultCallbackResponse(BaseModel):
+    """Schema for response to B2C result callback."""
+
+    ResultCode: int = Field(
+        default=0, description="Result code (0=Success, other=Failure)."
+    )
+    ResultDesc: str = Field(
+        default="Result received and processed successfully.",
+        description="Result description.",
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "ResultCode": 0,
+                "ResultDesc": "Result received and processed successfully.",
+            }
+        }
+    )
+
+
+class B2CTimeoutCallback(BaseModel):
+    """Schema for B2C timeout notification sent to QueueTimeOutURL."""
+
+    Result: B2CResultMetadata = Field(..., description="Result metadata.")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "Result": {
+                    "ResultType": 0,
+                    "ResultCode": 0,
+                    "ResultDesc": "The service request is processed successfully.",
+                    "OriginatorConversationID": "12345-67890-1",
+                    "ConversationID": "AG_20170717_00006c6f7f5b8b6b1a62",
+                }
+            }
+        }
+    )
+
+
+class B2CTimeoutCallbackResponse(BaseModel):
+    """Schema for response to B2C timeout callback."""
+
+    ResultCode: int = Field(
+        default=0,
+        description="Result code (0=Success, other=Failure).",
+    )
+    ResultDesc: str = Field(
+        default="Timeout notification received and processed successfully.",
+        description="Result description.",
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "ResultCode": 0,
+                "ResultDesc": "Timeout notification received and processed successfully.",
+            }
+        }
+    )

mpesakit/B2C_account_top_up/B2C_account_top_up.py

@@ -0,0 +1,49 @@
+"""B2CAccountTopUp: Handles M-Pesa B2C Account Topup API interactions.
+
+This module provides functionality to initiate a B2C Account Topup transaction and handle result/timeout notifications
+using the M-Pesa API. Requires a valid access token for authentication and uses the HttpClient for HTTP requests.
+"""
+
+from pydantic import BaseModel, ConfigDict
+from mpesakit.auth import TokenManager
+from mpesakit.http_client import HttpClient
+
+from .schemas import (
+    B2CAccountTopUpRequest,
+    B2CAccountTopUpResponse,
+)
+
+
+class B2CAccountTopUp(BaseModel):
+    """Represents the B2C Account TopUp API client for M-Pesa operations.
+
+    https://developer.safaricom.co.ke/APIs/B2CAccountTopUp
+
+    Attributes:
+        http_client (HttpClient): HTTP client for making requests to the M-Pesa API.
+        token_manager (TokenManager): Manages access tokens for authentication.
+    """
+
+    http_client: HttpClient
+    token_manager: TokenManager
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def topup(self, request: B2CAccountTopUpRequest) -> B2CAccountTopUpResponse:
+        """Initiates a B2C Account TopUp transaction.
+
+        Args:
+            request (B2CAccountTopUpRequest): The B2C Account TopUp request data.
+
+        Returns:
+            B2CAccountTopUpResponse: Response from the M-Pesa API.
+        """
+        url = "/mpesa/b2b/v1/paymentrequest"
+        headers = {
+            "Authorization": f"Bearer {self.token_manager.get_token()}",
+            "Content-Type": "application/json",
+        }
+        response_data = self.http_client.post(
+            url, json=request.model_dump(mode="json"), headers=headers
+        )
+        return B2CAccountTopUpResponse(**response_data)

mpesakit/B2C_account_top_up/__init__.py

@@ -0,0 +1,19 @@
+from .schemas import (
+    B2CAccountTopUpRequest,
+    B2CAccountTopUpResponse,
+    B2CAccountTopUpCallback,
+    B2CAccountTopUpCallbackResponse,
+    B2CAccountTopUpTimeoutCallback,
+    B2CAccountTopUpTimeoutCallbackResponse,
+)
+from .B2C_account_top_up import B2CAccountTopUp
+
+__all__ = [
+    "B2CAccountTopUp",
+    "B2CAccountTopUpRequest",
+    "B2CAccountTopUpResponse",
+    "B2CAccountTopUpCallback",
+    "B2CAccountTopUpCallbackResponse",
+    "B2CAccountTopUpTimeoutCallback",
+    "B2CAccountTopUpTimeoutCallbackResponse",
+]