pybkash 0.1.0__py3-none-any.whl

pybkash/__init__.py

@@ -0,0 +1,6 @@
+from .main import Client, AsyncClient
+from .token_manager import Token, AsyncToken
+from .exceptions import APIError
+
+__all__ = ['Token', 'AsyncToken', 'Client', 'AsyncClient', 'APIError']
+

pybkash/exception_handlers.py

@@ -0,0 +1,10 @@
+from .exceptions import APIError
+
+def raise_api_exception(response: dict):
+    status_code = response.get("statusCode")
+    if not status_code: # no status_code sent by api, the api does it when nothing goes wrong
+        return
+    if status_code == "0000":
+        return
+    raise APIError(status_code=response["statusCode"], message=response["statusMessage"])
+

pybkash/exceptions.py

@@ -0,0 +1,8 @@
+class APIError(Exception):
+    def __init__(self, status_code: str, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[{self.status_code}] {self.message}"

pybkash/main.py

@@ -0,0 +1,570 @@
+from httpx import Client as SyncClient, AsyncClient as HttpxAsyncClient
+from .token_manager import Token, AsyncToken
+from .exception_handlers import raise_api_exception
+from .models import ( 
+    PaymentCreation,
+    AgreementCreation, 
+    PaymentExecution, 
+    AgreementExecution, 
+    RefundExecution, 
+    AgreementQuery, 
+    PaymentQuery,
+    Transaction,
+)
+
+
+class BaseClient:
+    def _create_agreement_object(self, response: dict) -> AgreementCreation:
+        return AgreementCreation(
+            status_code=response["statusCode"],
+            status_message=response["statusMessage"],
+            payment_id=response["paymentID"],
+            bkash_url=response["bkashURL"],
+            callback_url=response["callbackURL"],
+            success_callback=response["successCallbackURL"],
+            failure_callback=response["failureCallbackURL"],
+            cancel_callback=response["cancelledCallbackURL"],
+            payer_reference=response["payerReference"],
+            agreement_status=response["agreementStatus"],
+            agreement_create_time=response["agreementCreateTime"],
+        )
+
+    def _create_payment_object(self, payment_response: dict) -> PaymentCreation:
+        payment = PaymentCreation(
+            status_code=payment_response["statusCode"],
+            status_message=payment_response["statusMessage"],
+            payment_id=payment_response["paymentID"],
+            bkash_url=payment_response["bkashURL"],
+            callback_url=payment_response["callbackURL"],
+            success_callback=payment_response["successCallbackURL"],
+            failure_callback=payment_response["failureCallbackURL"],
+            cancel_callback=payment_response["cancelledCallbackURL"],
+        )
+        return payment
+
+
+
+    def _create_payment_execution_object(self, response: dict) -> PaymentExecution:
+        return PaymentExecution(
+            status_code=response["statusCode"],
+            status_message=response["statusMessage"],
+            payment_id=response["paymentID"],
+            payer_reference=response["payerReference"],
+            customer_msisdn=response["customerMsisdn"],
+            trx_id=response["trxID"],
+            amount=response["amount"],
+            transaction_status=response["transactionStatus"],
+            payment_execute_time=response["paymentExecuteTime"],
+            currency=response["currency"],
+            intent=response["intent"],
+            merchant_invoice_number=response["merchantInvoiceNumber"],
+            agreement_id=response.get("agreementID"),
+        )
+
+
+    def _create_agreement_execution_object(self, response: dict) -> AgreementExecution:
+        return AgreementExecution(
+            status_code=response["statusCode"],
+            status_message=response["statusMessage"],
+            payment_id=response["paymentID"],
+            agreement_id=response["agreementID"],
+            payer_reference=response["payerReference"],
+            customer_msisdn=response["customerMsisdn"],
+            agreement_execute_time=response["agreementExecuteTime"],
+            agreement_status=response["agreementStatus"],
+        )
+
+    def _create_agreement_query_object(self, response: dict) -> AgreementQuery:
+        return AgreementQuery(
+            status_code=response["statusCode"],
+            status_message=response["statusMessage"],
+            payment_id=response["paymentID"],
+            agreement_id=response["agreementID"],
+            payer_reference=response["payerReference"],
+            payer_account=response["payerAccount"], 
+            payer_type=response["payerType"], 
+            agreement_status=response["agreementStatus"],
+            agreement_create_time=response["agreementCreateTime"],
+            agreement_execute_time=response["agreementExecuteTime"],
+            mode=response["mode"],
+            verification_status=response["verificationStatus"],
+        )
+
+    def _create_payment_query_object(self, response: dict) -> PaymentQuery:
+        return PaymentQuery(
+            status_code=response["statusCode"],
+            status_message=response["statusMessage"],
+            payment_id=response["paymentID"],
+            payer_reference=response["payerReference"],
+            mode=response["mode"],
+            payment_create_time=response["paymentCreateTime"],
+            amount=response["amount"],
+            currency=response["currency"],
+            intent=response["intent"],
+            merchant_invoice=response["merchantInvoice"],
+            transaction_status=response["transactionStatus"],
+            verification_status=response["verificationStatus"],
+            agreement_status=response.get("agreementStatus"),
+            agreement_create_time=response.get("agreementCreateTime"),
+            agreement_execute_time=response.get("agreementExecuteTime"),
+            agreement_id=response.get("agreementID"),
+        )
+
+    def _create_refund_execution_object(self, response: dict) -> RefundExecution:
+        return RefundExecution(
+            original_trx_id=response["originalTrxID"],
+            refund_trx_id=response["refundTrxID"],
+            transaction_status=response["transactionStatus"],
+            amount=response["amount"],
+            currency=response["currency"],
+            completed_time=response["completedTime"],
+            status_code=response["statusCode"],
+            status_message=response["statusMessage"],
+        )
+
+
+    def _create_trx_object(self, response: dict) -> Transaction:
+        return Transaction(
+            # always-present fields → strict access
+            trx_id=response["trxID"],
+            initiation_time=response["initiationTime"],
+            completed_time=response["completedTime"],
+            transaction_type=response["transactionType"],
+            customer_msisdn=response["customerMsisdn"],
+            payer_account=response["payerAccount"],
+            transaction_status=response["transactionStatus"],
+            amount=response["amount"],
+            currency=response["currency"],
+            organization_short_code=response["organizationShortCode"],
+            status_code=response["statusCode"],
+            status_message=response["statusMessage"],
+
+            # optional fields → safe access
+            service_fee=response.get("serviceFee"),
+            payer_type=response.get("payerType"),
+            credited_amount=response.get("creditedAmount"),
+            max_refundable_amount=response.get("maxRefundableAmount"),
+            original_trx_amount=response.get("originalTrxAmount"),
+        )
+
+
+class Client(BaseClient):
+    def __init__(self, token: Token) -> None:
+        if not isinstance(token, Token):
+            raise TypeError(
+                    f"Client requires a Token instance, got {type(token).__name__} instead. "
+                    f"Use AsyncToken with the asynchronous AsyncClient class."
+                )
+        self.token = token
+        self._client = SyncClient(base_url=token.base_url)
+
+    def close(self) -> None:
+        """Closes the HTTP client connection.
+        
+        Should be called when done using the client to clean up resources.
+        """
+        self._client.close()
+
+    def create_agreement(self, callback_url: str, payer_reference: str) -> AgreementCreation:
+        """Creates a new bKash agreement for tokenized payments.
+        
+        Args:
+            callback_url: URL where bKash redirects after user authentication
+            payer_reference: Unique reference for the payer
+        
+        Returns:
+            AgreementCreation: Agreement creation response with payment_id and bkash_url
+        
+        Raises:
+            APIError: If agreement creation fails
+        """
+        data = {
+            "mode": "0000",
+            "callbackURL": callback_url,
+            "payerReference": payer_reference,
+        }
+        response = self._client.post(url="/tokenized/checkout/create",headers=self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return self._create_agreement_object(response_json)
+
+    def create_payment(self, callback_url: str, payer_reference: str, amount: int, agreement_id: str | None = None, invoice_number: str | None = None, merchant_association_info: str | None = None) -> PaymentCreation: 
+        """Creates a new bKash payment.
+        
+        Args:
+            callback_url: URL where bKash redirects after user authentication
+            payer_reference: Unique reference for the payer
+            amount: Payment amount in BDT
+            agreement_id: Optional agreement ID for tokenized payment (enables PIN-only flow)
+            invoice_number: Optional merchant invoice number
+            merchant_association_info: Optional merchant association information
+        
+        Returns:
+            PaymentCreation: Payment creation response with payment_id and bkash_url
+        
+        Raises:
+            APIError: If payment creation fails
+        """
+        data = {  
+            "mode": "0011", # mode for url based payment without agreement
+            "payerReference": str(payer_reference),
+            "callbackURL": callback_url,
+            "amount": amount,
+            "currency": "BDT",   
+            "intent": "sale",
+            "merchantInvoiceNumber": "0000"
+        }
+        if agreement_id:
+            data["mode"] = "0001" # change mode for agreement payment
+            data["agreementID"] = agreement_id
+        if invoice_number:
+            data["merchantInvoiceNumber"] = invoice_number
+        if merchant_association_info:
+            data["merchantAssociationInfo"] = merchant_association_info 
+        response = self._client.post(url="/tokenized/checkout/create",headers=self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return self._create_payment_object(response_json)
+    def _execute(self, payment_id: str) -> dict:
+        """Executes Agreements and Payments via payment_id"""
+        data = {
+            "paymentID" : payment_id
+        }
+        response = self._client.post(url="/tokenized/checkout/execute",headers=self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return response_json
+    def execute_payment(self, payment_id: str) -> PaymentExecution:
+        """Executes a payment after user authentication.
+        
+        Args:
+            payment_id: The payment ID from create_payment()
+        
+        Returns:
+            PaymentExecution: Execution response with transaction details and status
+        
+        Raises:
+            APIError: If payment execution fails
+        """
+        response_json: dict = self._execute(payment_id)
+        return self._create_payment_execution_object(response_json)
+
+    def execute_agreement(self, payment_id: str) -> AgreementExecution:
+        """Executes an agreement after user authentication.
+        
+        Args:
+            payment_id: The payment ID from create_agreement()
+        
+        Returns:
+            AgreementExecution: Execution response with agreement_id and status
+        
+        Raises:
+            APIError: If agreement execution fails
+        """
+        response: dict = self._execute(payment_id)
+        return self._create_agreement_execution_object(response)
+
+    def _query(self, payment_id: str) -> dict:
+        """queries payments and agreements"""
+        data = {
+            "paymentID" : payment_id
+        }
+        response = self._client.post(url="/tokenized/checkout/payment/status",headers=self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return response_json
+
+    def query_agreement(self, payment_id: str) -> AgreementQuery:
+        """Queries the status and details of an agreement.
+        
+        Args:
+            payment_id: The payment ID from create_agreement()
+        
+        Returns:
+            AgreementQuery: Agreement details including status and agreement_id
+        
+        Raises:
+            APIError: If query fails
+        """
+        response_json: dict = self._query(payment_id)
+        return self._create_agreement_query_object(response_json)
+
+    def query_payment(self, payment_id: str) -> PaymentQuery:
+        """Queries the status and details of a payment.
+        
+        Args:
+            payment_id: The payment ID from create_payment()
+        
+        Returns:
+            PaymentQuery: Payment details including status and transaction information
+        
+        Raises:
+            APIError: If query fails
+        """
+        response: dict = self._query(payment_id)
+        return self._create_payment_query_object(response)
+
+    def execute_refund(self, payment_id: str, trx_id: str, refund_amount: int, sku: str | None = None, reason: str | None = None) -> RefundExecution:
+        """Executes a refund for a completed payment.
+        
+        Args:
+            payment_id: The payment ID from the original payment
+            trx_id: The transaction ID from the original payment
+            refund_amount: Amount to refund in BDT
+            sku: Optional SKU/product identifier
+            reason: Optional reason for the refund
+        
+        Returns:
+            RefundExecution: Refund transaction details including refund_trx_id and status
+        
+        Raises:
+            APIError: If refund fails
+        """
+        data = {
+            "paymentID": payment_id,
+            "trxID": trx_id,
+            "amount": str(refund_amount),
+            "sku": sku or "not_provided",
+            "reason": reason or "not_provided"
+        }
+        response = self._client.post(url="/tokenized/checkout/payment/refund", headers=self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return self._create_refund_execution_object(response_json)
+
+    def search_trx(self, trx_id: str) -> Transaction:
+        """Searches for a transaction by transaction ID.
+        
+        Args:
+            trx_id: The transaction ID to search for
+        
+        Returns:
+            Transaction: Transaction details including amount, status, and timestamps
+        
+        Raises:
+            APIError: If transaction not found
+        """
+        data = {
+            "trxID" : trx_id
+        }
+        response = self._client.post(url="/tokenized/checkout/general/searchTransaction",headers=self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return self._create_trx_object(response_json)
+
+
+class AsyncClient(BaseClient):
+    def __init__(self, token: AsyncToken) -> None:
+        if not isinstance(token, AsyncToken): # raise error if provided token is not async
+            raise TypeError(
+                f"AsyncClient requires an AsyncToken instance, got {type(token).__name__} instead. "
+                f"Use Token with the synchronous Client class."
+            )
+        self.token = token
+        self._client = HttpxAsyncClient(base_url=token.base_url)
+
+    async def aclose(self) -> None:
+        """Closes the async HTTP client connection.
+        
+        Should be called when done using the client to clean up resources.
+        """
+        await self._client.aclose()
+
+    async def create_agreement(self, callback_url: str, payer_reference: str) -> AgreementCreation:
+        """Creates a new bKash agreement for tokenized payments.
+        
+        Args:
+            callback_url: URL where bKash redirects after user authentication
+            payer_reference: Unique reference for the payer
+        
+        Returns:
+            AgreementCreation: Agreement creation response with payment_id and bkash_url
+        
+        Raises:
+            APIError: If agreement creation fails
+        """
+        data = {
+            "mode": "0000",
+            "callbackURL": callback_url,
+            "payerReference": payer_reference,
+        }
+        response = await self._client.post(url="/tokenized/checkout/create",headers= await self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return self._create_agreement_object(response_json)
+
+    async def create_payment(self, callback_url: str, payer_reference: str, amount: int, agreement_id: str | None = None, invoice_number: str | None = None, merchant_association_info: str | None = None) -> PaymentCreation: 
+        """Creates a new bKash payment.
+        
+        Args:
+            callback_url: URL where bKash redirects after user authentication
+            payer_reference: Unique reference for the payer
+            amount: Payment amount in BDT
+            agreement_id: Optional agreement ID for tokenized payment (enables PIN-only flow)
+            invoice_number: Optional merchant invoice number
+            merchant_association_info: Optional merchant association information
+        
+        Returns:
+            PaymentCreation: Payment creation response with payment_id and bkash_url
+        
+        Raises:
+            APIError: If payment creation fails
+        """
+        data = {  
+            "mode": "0011", # mode for url based payment without agreement
+            "payerReference": str(payer_reference),
+            "callbackURL": callback_url,
+            "amount": amount,
+            "currency": "BDT",   
+            "intent": "sale",
+            "merchantInvoiceNumber": "0000"
+        }
+        if agreement_id:
+            data["mode"] = "0001" # change mode for agreement payment
+            data["agreementID"] = agreement_id
+        if invoice_number:
+            data["merchantInvoiceNumber"] = invoice_number
+        if merchant_association_info:
+            data["merchantAssociationInfo"] = merchant_association_info 
+        response = await self._client.post(url="/tokenized/checkout/create",headers=await self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return self._create_payment_object(response_json)
+    async def _execute(self, payment_id: str) -> dict:
+        """Executes Agreements and Payments via payment_id"""
+        data = {
+            "paymentID" : payment_id
+        }
+        response = await self._client.post(url="/tokenized/checkout/execute",headers= await self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return response_json
+    async def execute_payment(self, payment_id: str) -> PaymentExecution:
+        """Executes a payment after user authentication.
+        
+        Args:
+            payment_id: The payment ID from create_payment()
+        
+        Returns:
+            PaymentExecution: Execution response with transaction details and status
+        
+        Raises:
+            APIError: If payment execution fails
+        """
+        response_json: dict = await self._execute(payment_id)
+        return self._create_payment_execution_object(response_json)
+
+    async def execute_agreement(self, payment_id: str) -> AgreementExecution:
+        """Executes an agreement after user authentication.
+        
+        Args:
+            payment_id: The payment ID from create_agreement()
+        
+        Returns:
+            AgreementExecution: Execution response with agreement_id and status
+        
+        Raises:
+            APIError: If agreement execution fails
+        """
+        response: dict = await self._execute(payment_id)
+        return self._create_agreement_execution_object(response)
+
+    async def _query(self, payment_id: str) -> dict:
+        """queries payments and agreements"""
+        data = {
+            "paymentID" : payment_id
+        }
+        response = await self._client.post(url="/tokenized/checkout/payment/status",headers=await self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return response_json
+
+    async def query_agreement(self, payment_id: str) -> AgreementQuery:
+        """Queries the status and details of an agreement.
+        
+        Args:
+            payment_id: The payment ID from create_agreement()
+        
+        Returns:
+            AgreementQuery: Agreement details including status and agreement_id
+        
+        Raises:
+            APIError: If query fails
+        """
+        response_json: dict = await self._query(payment_id)
+        return self._create_agreement_query_object(response_json)
+
+    async def query_payment(self, payment_id: str) -> PaymentQuery:
+        """Queries the status and details of a payment.
+        
+        Args:
+            payment_id: The payment ID from create_payment()
+        
+        Returns:
+            PaymentQuery: Payment details including status and transaction information
+        
+        Raises:
+            APIError: If query fails
+        """
+        response: dict = await self._query(payment_id)
+        return self._create_payment_query_object(response)
+
+    async def execute_refund(self, payment_id: str, trx_id: str, refund_amount: int, sku: str | None = None, reason: str | None = None) -> RefundExecution:
+        """Executes a refund for a completed payment.
+        
+        Args:
+            payment_id: The payment ID from the original payment
+            trx_id: The transaction ID from the original payment
+            refund_amount: Amount to refund in BDT
+            sku: Optional SKU/product identifier
+            reason: Optional reason for the refund
+        
+        Returns:
+            Refund: Refund transaction details including refund_trx_id and status
+        
+        Raises:
+            APIError: If refund fails
+        """
+        data = {
+            "paymentID": payment_id,
+            "trxID": trx_id,
+            "amount": str(refund_amount),
+            "sku": sku or "not_provided",
+            "reason": reason or "not_provided"
+        }
+        response = await self._client.post(url="/tokenized/checkout/payment/refund", headers=await self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return self._create_refund_execution_object(response_json)
+
+    async def search_trx(self, trx_id: str) -> Transaction:
+        """Searches for a transaction by transaction ID.
+        
+        Args:
+            trx_id: The transaction ID to search for
+        
+        Returns:
+            Transaction: Transaction details including amount, status, and timestamps
+        
+        Raises:
+            APIError: If transaction not found
+        """
+        data = {
+            "trxID" : trx_id
+        }
+        response = await self._client.post(url="/tokenized/checkout/general/searchTransaction",headers=await self.token.get_headers(), json=data)
+        response.raise_for_status()
+        response_json = response.json()
+        raise_api_exception(response_json)
+        return self._create_trx_object(response_json)

pybkash/models.py

@@ -0,0 +1,324 @@
+class CreationBase:
+    def __init__(
+        self,
+        status_code: str | int,
+        status_message: str,
+        payment_id: str,
+        bkash_url: str,
+        callback_url: str,
+        success_callback: str,
+        failure_callback: str,
+        cancel_callback: str,
+    ) -> None:
+        self.status_code = status_code
+        self.status_message = status_message
+        self.payment_id = payment_id
+        self.bkash_url = bkash_url
+        self.callback_url = callback_url
+        self.success_callback = success_callback
+        self.failure_callback = failure_callback
+        self.cancel_callback = cancel_callback
+
+class StatusMixin:
+    status: str
+
+    def is_complete(self) -> bool:
+        return self.status.upper() == "COMPLETED"
+
+class ExecutionBase(StatusMixin):
+    def __init__(
+        self,
+        status_code: str,
+        status_message: str,
+        payment_id: str,
+        agreement_id: str | None,
+        payer_reference: str,
+        customer_msisdn: str,
+    ) -> None:
+        self.status_code = status_code
+        self.status_message = status_message
+        self.payment_id = payment_id
+        self.agreement_id = agreement_id
+        self.payer_reference = payer_reference
+        self.customer_msisdn = customer_msisdn
+
+class QueryBase(StatusMixin):
+    def __init__(
+        self,
+        status_code: str,
+        status_message: str,
+        payment_id: str,
+        payer_reference: str,
+        agreement_id: str | None = None,
+        agreement_status: str | None = None,
+        agreement_create_time: str | None = None,
+        agreement_execute_time: str | None = None,
+        verification_status: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.status_message = status_message
+        self.payment_id = payment_id
+        self.payer_reference = payer_reference
+        self.agreement_id = agreement_id
+        self.agreement_status = agreement_status
+        self.agreement_create_time = agreement_create_time
+        self.agreement_execute_time = agreement_execute_time
+        self.verification_status = verification_status
+
+class PaymentCreation(CreationBase):
+    def __init__(
+        self,
+        status_code: int,
+        status_message: str,
+        payment_id: str,
+        bkash_url: str,
+        callback_url: str,
+        success_callback: str,
+        failure_callback: str,
+        cancel_callback: str,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            status_message=status_message,
+            payment_id=payment_id,
+            bkash_url=bkash_url,
+            callback_url=callback_url,
+            success_callback=success_callback,
+            failure_callback=failure_callback,
+            cancel_callback=cancel_callback,
+        )
+
+class AgreementCreation(CreationBase):
+    def __init__(
+        self,
+        status_code: str,
+        status_message: str,
+        payment_id: str,
+        bkash_url: str,
+        callback_url: str,
+        success_callback: str,
+        failure_callback: str,
+        cancel_callback: str,
+        payer_reference: str,
+        agreement_status: str,
+        agreement_create_time: str,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            status_message=status_message,
+            payment_id=payment_id,
+            bkash_url=bkash_url,
+            callback_url=callback_url,
+            success_callback=success_callback,
+            failure_callback=failure_callback,
+            cancel_callback=cancel_callback,
+        )
+
+        self.payer_reference = payer_reference
+        self.agreement_status = agreement_status
+        self.agreement_create_time = agreement_create_time
+
+class RefundExecution(StatusMixin):
+    def __init__(
+        self,
+        original_trx_id: str,
+        refund_trx_id: str,
+        transaction_status: str,
+        amount: str,
+        currency: str,
+        completed_time: str,
+        status_code: str,
+        status_message: str,
+    ) -> None:
+        self.status = transaction_status # universal status
+        self.trx_id = refund_trx_id # universal trx_id
+        self.original_trx_id = original_trx_id
+        self.refund_trx_id = refund_trx_id
+        self.transaction_status = transaction_status
+        self.amount = amount
+        self.currency = currency
+        self.completed_time = completed_time
+        self.status_code = status_code
+        self.status_message = status_message
+
+
+class AgreementExecution(ExecutionBase):
+    def __init__(
+        self,
+        status_code: str,
+        status_message: str,
+        payment_id: str,
+        agreement_id: str,
+        payer_reference: str,
+        customer_msisdn: str,
+        agreement_execute_time: str,
+        agreement_status: str,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            status_message=status_message,
+            payment_id=payment_id,
+            agreement_id=agreement_id,
+            payer_reference=payer_reference,
+            customer_msisdn=customer_msisdn,
+        )
+
+        self.status = agreement_status  # universal status
+        self.agreement_status = agreement_status
+        self.agreement_execute_time = agreement_execute_time
+
+class PaymentExecution(ExecutionBase):
+    def __init__(
+        self,
+        status_code: str,
+        status_message: str,
+        payment_id: str,
+        agreement_id: str | None,
+        payer_reference: str,
+        customer_msisdn: str,
+        trx_id: str,
+        amount: str,
+        transaction_status: str,
+        payment_execute_time: str,
+        currency: str,
+        intent: str,
+        merchant_invoice_number: str,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            status_message=status_message,
+            payment_id=payment_id,
+            agreement_id=agreement_id,
+            payer_reference=payer_reference,
+            customer_msisdn=customer_msisdn,
+        )
+
+        self.status = transaction_status  # universal status
+        self.trx_id = trx_id
+        self.transaction_status = transaction_status
+        self.amount = amount
+        self.payment_execute_time = payment_execute_time
+        self.currency = currency
+        self.intent = intent
+        self.merchant_invoice_number = merchant_invoice_number
+
+class AgreementQuery(QueryBase):
+    def __init__(
+        self,
+        status_code: str,
+        status_message: str,
+        payment_id: str,
+        agreement_id: str,
+        payer_reference: str,
+        payer_account: str,
+        payer_type: str,
+        agreement_status: str,
+        agreement_create_time: str,
+        agreement_execute_time: str,
+        mode: str,
+        verification_status: str,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            status_message=status_message,
+            payment_id=payment_id,
+            payer_reference=payer_reference,
+            agreement_id=agreement_id,
+            agreement_status=agreement_status,
+            agreement_create_time=agreement_create_time,
+            agreement_execute_time=agreement_execute_time,
+            verification_status=verification_status,
+        )
+        self.status = agreement_status
+        self.payer_account = payer_account
+        self.payer_type = payer_type
+        self.mode = mode
+
+class PaymentQuery(QueryBase):
+    def __init__(
+        self,
+        status_code: str,
+        status_message: str,
+        payment_id: str,
+        payer_reference: str,
+        mode: str,
+        payment_create_time: str,
+        amount: str,
+        currency: str,
+        intent: str,
+        merchant_invoice: str,
+        transaction_status: str,
+        verification_status: str,
+        agreement_id: str | None,
+        agreement_status: str | None,
+        agreement_create_time: str | None,
+        agreement_execute_time: str | None,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            status_message=status_message,
+            payment_id=payment_id,
+            payer_reference=payer_reference,
+            agreement_id=agreement_id,
+            agreement_status=agreement_status,
+            agreement_create_time=agreement_create_time,
+            agreement_execute_time=agreement_execute_time,
+            verification_status=verification_status,
+        )
+
+        self.status = transaction_status
+        self.transaction_status = transaction_status
+        self.mode = mode
+        self.payment_create_time = payment_create_time
+        self.amount = amount
+        self.currency = currency
+        self.intent = intent
+        self.merchant_invoice = merchant_invoice
+
+class Transaction(StatusMixin):
+    def __init__(
+        self,
+        trx_id: str,
+        initiation_time: str,
+        completed_time: str,
+        transaction_type: str,
+        customer_msisdn: str,
+        payer_account: str,
+        transaction_status: str,
+        amount: str,
+        currency: str,
+        organization_short_code: str,
+        status_code: str,
+        status_message: str,
+
+        # following 4 not present in refund transactions
+        service_fee: str | None = None,
+        payer_type: str | None = None,
+        credited_amount: str | None = None,
+        max_refundable_amount: str | None = None,
+
+        # this key is only sent for the refund transcations
+        original_trx_amount: str | None = None,
+    ) -> None:
+        self.status = transaction_status
+        self.trx_id = trx_id
+        self.initiation_time = initiation_time
+        self.completed_time = completed_time
+        self.transaction_type = transaction_type
+        self.customer_msisdn = customer_msisdn
+        self.payer_account = payer_account
+        self.transaction_status = transaction_status
+        self.amount = amount
+        self.currency = currency
+        self.organization_short_code = organization_short_code
+        self.status_code = status_code
+        self.status_message = status_message
+
+        self.service_fee = service_fee
+        self.payer_type = payer_type
+        self.credited_amount = credited_amount
+        self.max_refundable_amount = max_refundable_amount
+
+        self.original_trx_amount = original_trx_amount
+
+

pybkash/token_manager.py

@@ -0,0 +1,174 @@
+from httpx import post, AsyncClient as HttpxAsyncClient
+from time import time
+from .exception_handlers import raise_api_exception
+
+
+class BaseToken:
+    """Base class for bKash token management with shared logic."""
+    def __init__(self, username: str, password: str, app_key: str, app_secret: str, sandbox=False) -> None:
+        self.base_url = "https://tokenized.pay.bka.sh/v1.2.0-beta"
+        if sandbox:
+            self.base_url = "https://tokenized.sandbox.bka.sh/v1.2.0-beta"
+        
+        self.username = username
+        self.app_key = app_key
+        self.timestamp = 0
+        self.expires_in = 0
+        self.id_token = None
+        
+        self.headers = {
+            "username": username,
+            "password": password
+        }
+        self.data = {
+            "app_key": app_key,
+            "app_secret": app_secret
+        }
+    
+    def _load_token(self, token: dict) -> None:
+        """Load token data into instance variables."""
+        self.id_token = token.get("id_token")
+        self.timestamp = token.get("timestamp")
+        self.expires_in = token.get("expires_in")
+    
+    def _is_token_valid(self) -> bool:
+        """Check if current token is valid."""
+        return self.id_token and not (time() - self.timestamp > self.expires_in)
+    
+    def _process_token_response(self, token_obj: dict) -> dict:
+        """Process raw token response from API."""
+        raise_api_exception(token_obj)
+        token_obj["expires_in"] -= 10  # keeping a 10 seconds overhead
+        token_obj["timestamp"] = time()  # adding a key to keep track of when it was fetched
+        return token_obj
+
+
+class Token(BaseToken):
+    """Synchronous bKash token manager."""
+    
+    def _fetch_from_api(self) -> dict:
+        """Fetch a new token from the bKash API."""
+        response = post(
+            url=f"{self.base_url}/tokenized/checkout/token/grant",
+            headers=self.headers,
+            json=self.data
+        )
+        response.raise_for_status()
+        token_obj = response.json()
+        return self._process_token_response(token_obj)
+    
+    def get_token_id(self) -> str:
+        """Gets a valid bKash API token ID.
+        
+        Returns a cached token if available, otherwise fetches a new one.
+        
+        Returns:
+            str: Valid bKash API token ID
+        
+        Raises:
+            APIError: If token fetch fails
+        """
+        if self._is_token_valid():
+            return self.id_token
+        
+        token = self._fetch_from_api()
+        self._load_token(token)
+        return self.id_token
+    
+    def get_new_token_id(self) -> str:
+        """Forces a fresh token fetch from the bKash API.
+        
+        Returns:
+            str: New bKash API token ID
+        
+        Raises:
+            APIError: If token fetch fails
+        """
+        token = self._fetch_from_api()
+        self._load_token(token)
+        return self.id_token
+    
+    def get_headers(self) -> dict:
+        """Returns authorization headers for bKash API requests.
+        
+        Returns:
+            dict: Headers with authorization token and X-APP-Key
+        
+        Raises:
+            APIError: If token retrieval fails
+        """
+        return {
+            "authorization": str(self.get_token_id()),
+            "X-APP-Key": self.app_key
+        }
+
+
+class AsyncToken(BaseToken):
+    """Asynchronous bKash token manager."""
+    
+    def __init__(self, username: str, password: str, app_key: str, app_secret: str, sandbox=False) -> None:
+        super().__init__(username, password, app_key, app_secret, sandbox)
+        self._client = HttpxAsyncClient(base_url=self.base_url)
+    
+    async def aclose(self) -> None:
+        """Closes the async HTTP client connection.
+        
+        Should be called when done using the token manager to clean up resources.
+        """
+        await self._client.aclose()
+    
+    async def _fetch_from_api(self) -> dict:
+        """Fetch a new token from the bKash API."""
+        response = await self._client.post(
+            url="/tokenized/checkout/token/grant",
+            headers=self.headers,
+            json=self.data
+        )
+        response.raise_for_status()
+        token_obj = response.json()
+        return self._process_token_response(token_obj)
+    
+    async def get_token_id(self) -> str:
+        """Gets a valid bKash API token ID.
+        
+        Returns a cached token if available, otherwise fetches a new one.
+        
+        Returns:
+            str: Valid bKash API token ID
+        
+        Raises:
+            APIError: If token fetch fails
+        """
+        if self._is_token_valid():
+            return self.id_token
+        
+        token = await self._fetch_from_api()
+        self._load_token(token)
+        return self.id_token
+    
+    async def get_new_token_id(self) -> str:
+        """Forces a fresh token fetch from the bKash API.
+        
+        Returns:
+            str: New bKash API token ID
+        
+        Raises:
+            APIError: If token fetch fails
+        """
+        token = await self._fetch_from_api()
+        self._load_token(token)
+        return self.id_token
+    
+    async def get_headers(self) -> dict:
+        """Returns authorization headers for bKash API requests.
+        
+        Returns:
+            dict: Headers with authorization token and X-APP-Key
+        
+        Raises:
+            APIError: If token retrieval fails
+        """
+        return {
+            "authorization": str(await self.get_token_id()),
+            "X-APP-Key": self.app_key
+        }

pybkash-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: pybkash
+Version: 0.1.0
+Summary: A Pythonic client for the bKash payment gateway. Supports both synchronous and asynchronous usage and covers the entire API surface.
+Keywords: bkash,payments,fintech,api,bangladesh
+Author: Monazir Muhammad Doha
+Author-email: Monazir Muhammad Doha <mmdoha@houndsec.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Dist: httpx>=0.27.0
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/itsmmdoha/pybkash
+Project-URL: Issues, https://github.com/itsmmdoha/pybkash/issues
+Description-Content-Type: text/markdown
+
+# pybkash
+
+A Pythonic client for the bKash payment gateway. Supports both synchronous and asynchronous usage and covers the entire API surface.
+
+## Features
+
+1. Normal Payment
+2. Agreement Creation
+3. Agreement Payment
+4. Refund
+5. Search Transaction
+
+## Installation
+
+```bash
+pip install pybkash
+```
+
+## Usage
+
+### Synchronous Client
+
+```python
+from pybkash import Client, Token
+
+# First, initialize the token. This will be passed to the Client.
+token = Token(
+    username="your_username",
+    password="your_password", 
+    app_key="your_app_key",
+    app_secret="your_app_secret",
+    sandbox=True  # Use False for production
+)
+```
+
+Then, create a client object by passing the token:
+
+```python
+client = Client(token)
+```
+
+You can now use this client to perform various operations.
+
+#### Step 1: Create Payment
+
+```python
+payment = client.create_payment(
+    callback_url="https://yoursite.com/callback",
+    payer_reference="CUSTOMER001",  # Passing a phone or bKash number pre-populates the wallet number field on the bKash checkout page.
+    amount=1000  # Amount in BDT
+)
+```
+
+This returns a `PaymentCreation` object:
+
+* `payment.payment_id` is the ID bKash uses to identify individual payments.
+* `payment.bkash_url` is the payment URL — send the user to this page.
+
+After the user has completed the payment:
+
+#### Step 2: Execute Payment
+
+```python
+execution = client.execute_payment(payment.payment_id)
+```
+
+This returns a `PaymentExecution` object.
+
+```python
+# Verify completion
+if execution.is_complete():
+    print(f"Payment successful! TrxID: {execution.trx_id}")
+else:
+    print(f"Payment status: {execution.status}")
+```
+
+## Documentation
+
+For detailed synchronous and asynchronous usage information, including return types and attributes, see [docs](https://github.com/Itsmmdoha/pybkash/tree/main/docs).
+

pybkash-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pybkash/__init__.py,sha256=4Dyl98EJ6WeWPyAZCmetvPDNHA1vFitUUhSjWScZ8sc,189
+pybkash/exception_handlers.py,sha256=vc1s7wV4Hg6V8YUvwEb5pcvayIHAOuayYdR_fQa29K4,365
+pybkash/exceptions.py,sha256=pR5M0ZrArgjl2ZlKbVrA--VOXt1xeDPj9PkmPje9oxs,272
+pybkash/main.py,sha256=DhcM1LmCH6iv0LXNIScCFE-alYRQWSkR0ni0QG7shDI,23491
+pybkash/models.py,sha256=HCbTCHl4l8rJlZTZn4uFIUtsUCHMqEdYiKEZBhIUM68,10254
+pybkash/token_manager.py,sha256=dcBkgsYBnmbQooVvLf1DbsmRN-LjgszcLTmO44DKdR0,5552
+pybkash-0.1.0.dist-info/licenses/LICENSE,sha256=0ESUNlYYDS9EIQOFAAxUgqCvfGebM0vBKwkjXpnGSxo,1078
+pybkash-0.1.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+pybkash-0.1.0.dist-info/METADATA,sha256=H2rfXz68mR73HMJ6hnVdX5hIE5uuSKQ7eTNd_E349XE,2514
+pybkash-0.1.0.dist-info/RECORD,,

pybkash-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

pybkash-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Monazir Muhammad Doha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.