raqm-core 0.1.0__py3-none-any.whl

raqm_core/easypaisa.py

@@ -0,0 +1,77 @@
+import httpx
+
+from .headers.easypaisa import generate_auth_header
+from .schemas.easypaisa import (
+    EasyPaisaInquireTransactionResponse,
+    EasyPaisaMAResponse,
+    EasyPaisaOTCResponse,
+)
+
+
+class EasyPaisa:
+    def __init__(
+        self,
+        store_id: str,
+        username: str,
+        password: str,
+        sandbox: bool,
+        client: httpx.AsyncClient | None = None,
+    ):
+        self.store_id = store_id
+        self.username = username
+        self.password = password
+        self.sandbox = sandbox
+        self._client = client or httpx.AsyncClient()
+
+        self.base_url = (
+            "https://easypaystg.easypaisa.com.pk/easypay-service/rest/v4/"
+            if self.sandbox
+            else "https://easypay.easypaisa.com.pk/easypay-service/rest/v4/"
+        )
+
+    async def _post(self, endpoint: str, payload: dict) -> dict:
+        header = generate_auth_header(self.username, self.password)
+        response = await self._client.post(
+            self.base_url + endpoint,
+            json=payload,
+            headers={"Authorization": header},
+        )
+        return response.json()
+
+    async def pay_via_otc(
+        self, order_id: str, amount: str, email: str, msisdn: str, token_expiry: str
+    ):
+        request_payload = {
+            "orderId": order_id,
+            "storeId": self.store_id,
+            "transactionAmount": amount,
+            "transactionType": "OTC",
+            "msisdn": msisdn,
+            "emailAddress": email,
+            "tokenExpiry": token_expiry,
+        }
+        data = await self._post("initiate-otc-transaction", request_payload)
+        return EasyPaisaOTCResponse(**data)
+
+    async def pay_via_ma(
+        self, order_id: str, amount: str, email: str, mobile_number: str
+    ):
+        request_payload = {
+            "orderId": order_id,
+            "storeId": self.store_id,
+            "transactionAmount": amount,
+            "transactionType": "MA",
+            "mobileAccountNo": mobile_number,
+            "emailAddress": email,
+        }
+        data = await self._post("initiate-ma-transaction", request_payload)
+        return EasyPaisaMAResponse(**data)
+
+    async def inquire_transaction_status(self, order_id: str, account_number: str):
+        request_payload = {
+            "orderId": order_id,
+            "storeId": self.store_id,
+            "accountNum": account_number,
+        }
+        data = await self._post("inquire-transaction", request_payload)
+        return EasyPaisaInquireTransactionResponse(**data)

raqm_core/headers/easypaisa.py

@@ -0,0 +1,7 @@
+import base64
+
+
+def generate_auth_header(username: str, password: str) -> str:
+    encoded_string = str.encode(username + ":" + password)
+    base64_encoded = base64.b64encode(encoded_string)
+    return "Basic " + base64_encoded.decode()

raqm_core/headers/jazzcash.py

@@ -0,0 +1,10 @@
+from hashlib import sha256
+
+
+def generate_secure_hash(hash_key: str, params: dict) -> str:
+    values = "&".join(param[1] for param in sorted(params.items()))
+    my_str = hash_key + "&" + values
+
+    my_bytes = str.encode(my_str)
+    my_sha256 = sha256(my_bytes)
+    return my_sha256.hexdigest()

raqm_core/schemas/easypaisa.py

@@ -0,0 +1,66 @@
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class EasypaisaResponseCode(str, Enum):
+    SUCCESS = "0000"
+    SYSTEM_ERROR = "0001"
+    REQUIRED_FIELD_MISSING = "0002"
+    MERCHANT_ACCOUNT_NOT_ACTIVE = "0005"
+    INVALID_STORE_ID = "0006"
+    STORE_NOT_ACTIVE = "0007"
+    PAYMENT_METHOD_NOT_ENABLED = "0008"
+    INVALID_CREDENTIALS = "0010"
+    LOW_BALANCE = "0013"
+    ACCOUNT_DOES_NOT_EXIST = "0014"
+    INVALID_TOKEN_EXPIRY = "0015"
+    INVALID_EXPIRY = "0016"  # date should be future date
+
+
+class EasyPaisaResponse(BaseModel):
+    orderId: str = Field(
+        ..., min_length=1, description="Merchant’s system generated Order ID"
+    )
+    storeId: int = Field(
+        ge=0, description="Store ID generated during merchant registration in Easypaisa"
+    )
+    transactionDateTime: str = Field(
+        ..., description="Format = dd/MM/yyyy hh:mm [AM/PM]"
+    )
+    responseCode: EasypaisaResponseCode = Field(
+        ...,
+        min_length=4,
+        max_length=4,
+        description="Easypaisa generated response codes",
+    )
+    responseDesc: str = Field(
+        ..., min_length=3, description="Easypaisa generated response descriptions"
+    )
+
+
+class EasyPaisaMAResponse(EasyPaisaResponse):
+    transactionId: str = Field(..., description="Transaction ID of Ericsson (EWP ID)")
+
+
+class EasyPaisaOTCResponse(EasyPaisaResponse):
+    paymentToken: str = Field(..., min_length=1, description="Token generated by OTC")
+    paymentTokenExpiryDateTime: str = Field(
+        ..., description="Format = dd/MM/yyyy hh:mm [AM/PM]"
+    )
+
+
+class EasyPaisaInquireTransactionResponse(EasyPaisaResponse):
+    accountNum: str = Field(
+        ..., min_length=1, description="Merchant’s EWP Account Number"
+    )
+    storeName: str = Field(..., description="Store Name")
+    paymentToken: Optional[str] = Field(None, description="Token generated by OTC")
+    transactionStatus: str = Field(..., description="The status of transaction")
+    transactionAmount: str = Field(..., description="Total transaction amount ")
+    paymentTokenExpiryDateTime: Optional[str] = Field(
+        None, description="[Only For OTC] Format = dd/MM/yyyy hh:mm [AM/PM]"
+    )
+    msisdn: str = Field(..., description="Customer MSISDN")
+    paymentMode: str = Field(..., description="Type of transaction: OTC, MA, CC")

raqm_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: raqm-core
+Version: 0.1.0
+Summary: Unified Python SDK for Pakistani payment gateways (EasyPaisa, JazzCash, HBL, ABL, UBL, etc.)
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.0
+
+# raqm-core
+
+**Unified Python SDK for Pakistani payment gateways.**
+
+One async, type-safe interface across multiple processors — EasyPaisa, JazzCash, HBL, ABL, UBL, and more.
+
+> ⚠️ **Work in progress.** Currently only EasyPaisa is fully implemented. Contributions welcome!
+
+---
+
+## Supported Gateways
+
+| Gateway | Status |
+|---------|--------|
+| [EasyPaisa](https://easypaisa.com.pk) | ✅ Live |
+| [JazzCash](https://jazzcash.com.pk) | 🚧 Header utils ready |
+| HBL | 📅 Planned |
+| ABL | 📅 Planned |
+| UBL | 📅 Planned |
+| … | 📅 Your gateway here |
+
+---
+
+## Features
+
+- **Async-first** — built on `httpx.AsyncClient` for non-blocking I/O
+- **Type-safe** — all responses are validated through Pydantic models
+- **Consistent API** — same patterns across all gateways
+- **Mock-friendly** — inject your own `httpx.AsyncClient` for testing
+- **Minimal dependencies** — just `httpx` and `pydantic`
+
+---
+
+## Installation
+
+```bash
+pip install raqm-core
+```
+
+Or with `uv`:
+
+```bash
+uv add raqm-core
+```
+
+> Requires Python 3.12+.
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from raqm_core import EasyPaisa
+
+
+async def main():
+    ep = EasyPaisa(
+        store_id="43",
+        username="your_username",
+        password="your_password",
+        sandbox=True,
+    )
+
+    result = await ep.pay_via_ma(
+        order_id="order_123",
+        amount="1000.00",
+        email="customer@example.com",
+        mobile_number="03451234567",
+    )
+
+    print(f"Status: {result.responseCode} — {result.responseDesc}")
+    print(f"Transaction ID: {result.transactionId}")
+
+
+asyncio.run(main())
+```
+
+---
+
+## Usage
+
+### EasyPaisa
+
+#### Initialisation
+
+```python
+from raqm_core import EasyPaisa
+
+ep = EasyPaisa(
+    store_id="43",
+    username="your_username",
+    password="your_password",
+    sandbox=True,           # set False for production
+)
+```
+
+You can optionally inject your own `httpx.AsyncClient` — useful for testing with `httpx.MockTransport`:
+
+```python
+import httpx
+
+client = httpx.AsyncClient(...)
+ep = EasyPaisa(store_id="43", username="...", password="...", sandbox=True, client=client)
+```
+
+#### Mobile Account (MA) Payment
+
+```python
+result = await ep.pay_via_ma(
+    order_id="order_123",
+    amount="500.00",
+    email="customer@example.com",
+    mobile_number="03451234567",
+)
+
+# EasyPaisaMAResponse fields:
+result.orderId           # str
+result.storeId           # int
+result.transactionId     # str
+result.transactionDateTime  # str (dd/MM/yyyy hh:mm AM/PM)
+result.responseCode      # EasypaisaResponseCode (enum)
+result.responseDesc      # str
+```
+
+#### Over-the-Counter (OTC) Payment
+
+```python
+result = await ep.pay_via_otc(
+    order_id="order_456",
+    amount="1500.00",
+    email="customer@example.com",
+    msisdn="03451234567",
+    token_expiry="01/01/2025 11:59 PM",
+)
+
+# EasyPaisaOTCResponse fields (extends base):
+result.paymentToken              # str
+result.paymentTokenExpiryDateTime  # str
+```
+
+#### Transaction Inquiry
+
+```python
+result = await ep.inquire_transaction_status(
+    order_id="order_123",
+    account_number="123456789",
+)
+
+# EasyPaisaInquireTransactionResponse fields:
+result.transactionStatus   # str (e.g. "COMPLETED")
+result.transactionAmount   # str
+result.accountNum          # str
+result.storeName           # str
+result.msisdn              # str
+result.paymentMode         # str ("MA", "OTC", "CC")
+```
+
+---
+
+## Architecture
+
+Each payment gateway follows a consistent 3-layer structure:
+
+```
+src/
+├── <gateway>.py              # Client class — public API
+├── headers/
+│   └── <gateway>.py          # Auth / signing helpers
+└── schemas/
+    └── <gateway>.py          # Pydantic request/response models
+```
+
+Current structure:
+
+```
+src/
+├── easypaisa.py              # EasyPaisa client
+├── headers/
+│   ├── easypaisa.py          # Basic Auth header
+│   └── jazzcash.py           # SHA-256 secure hash
+└── schemas/
+    └── easypaisa.py          # EasyPaisa Pydantic models
+
+tests/
+├── test_easypaisa.py         # EasyPaisa integration tests
+└── headers/
+    ├── test_easypaisa.py     # Auth header unit tests
+    └── test_jazzcash.py      # Secure hash unit tests
+```
+
+---
+
+## Adding a New Gateway
+
+Want to add support for a new processor? Follow this checklist.
+
+### 1. Research the API
+
+Understand the gateway's:
+- Authentication mechanism (Basic Auth, HMAC, API key, etc.)
+- Endpoints and request/response formats
+- Error/response codes
+
+### 2. Create header helpers
+
+`src/headers/<gateway>.py` — authentication or signing logic.
+
+```python
+# src/headers/hbl.py
+def generate_signature(api_key: str, payload: dict) -> str:
+    ...
+```
+
+Write unit tests in `tests/headers/test_<gateway>.py`.
+
+### 3. Create Pydantic schemas
+
+`src/schemas/<gateway>.py` — response models and enums.
+
+```python
+# src/schemas/hbl.py
+from pydantic import BaseModel, Field
+
+
+class HBLResponse(BaseModel):
+    orderId: str = Field(...)
+    responseCode: str = Field(...)
+    responseDesc: str = Field(...)
+```
+
+### 4. Create the client class
+
+`src/<gateway>.py` — async client with a `_post()` helper and public methods.
+
+```python
+# src/hbl.py
+import httpx
+from .headers.hbl import generate_signature
+from .schemas.hbl import HBLResponse
+
+
+class HBL:
+    def __init__(self, api_key: str, sandbox: bool, client: httpx.AsyncClient | None = None):
+        self._client = client or httpx.AsyncClient()
+        ...
+
+    async def _post(self, endpoint: str, payload: dict) -> dict:
+        ...
+
+    async def pay(self, order_id: str, amount: str, ...) -> HBLResponse:
+        ...
+```
+
+### 5. Write integration tests
+
+`tests/test_<gateway>.py` — use `httpx.MockTransport` to mock responses.
+
+```python
+# tests/test_hbl.py
+import httpx
+import pytest
+from raqm_core import HBL
+
+
+@pytest.mark.asyncio
+async def test_pay_success():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status_code=200, json={...})
+
+    client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    hbl = HBL(api_key="test", sandbox=True, client=client)
+    result = await hbl.pay(...)
+    assert result.responseCode == "0000"
+```
+
+### 6. Update this README
+
+Add the new gateway to the **Supported Gateways** table with the appropriate status badge.
+
+---
+
+## Roadmap
+
+- [x] EasyPaisa (MA, OTC, inquiry)
+- [ ] JazzCash client + schemas
+- [ ] HBL payment gateway
+- [ ] ABL payment gateway
+- [ ] UBL payment gateway
+- [ ] Standardised error handling across gateways
+- [ ] Request/response logging middleware
+- [ ] CI/CD + automated testing
+
+---
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/your-username/raqm-core.git
+cd raqm-core
+
+# Create a virtual environment
+uv venv
+source .venv/bin/activate
+
+# Install dependencies
+uv sync
+
+# Run tests
+pytest
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! See [Adding a New Gateway](#adding-a-new-gateway) for the detailed guide.
+
+Please open an issue first to discuss your proposed changes.
+
+---
+
+## License
+
+MIT

raqm_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+raqm_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+raqm_core/easypaisa.py,sha256=3qOhp9iJwRqrb8ZV1CJJ-VjKOKSytJb6l5OzUoV_RJk,2518
+raqm_core/headers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+raqm_core/headers/easypaisa.py,sha256=4DFcfYpkohshhvIhwGTaMtFW5wuSut32Pj6NcWx0_48,238
+raqm_core/headers/jazzcash.py,sha256=2xObdRqXtrAl-s2czZhp1Ce2RRSratZPqYaSUJV71ag,297
+raqm_core/schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+raqm_core/schemas/easypaisa.py,sha256=8bUMiwg-UbIeQJCb1Dau7e8gB7Eb05XFN_g8LwUonBA,2346
+raqm_core-0.1.0.dist-info/METADATA,sha256=VPzt8L3L6lfwQ35gOZf7P--L7PLxLT37ik2S4qWGOCE,7335
+raqm_core-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+raqm_core-0.1.0.dist-info/top_level.txt,sha256=czlRB0RPtVl23KDFQZk7rtchAIxTZlNnNd5hFiXkDT4,10
+raqm_core-0.1.0.dist-info/RECORD,,

raqm_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

raqm_core-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+raqm_core