raqm-core 0.1.0__tar.gz

raqm_core-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,326 @@
+# 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/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "raqm-core"
+version = "0.1.0"
+description = "Unified Python SDK for Pakistani payment gateways (EasyPaisa, JazzCash, HBL, ABL, UBL, etc.)"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

raqm_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

raqm_core-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/raqm_core.egg-info/PKG-INFO

@@ -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/src/raqm_core.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/raqm_core/__init__.py
+src/raqm_core/easypaisa.py
+src/raqm_core.egg-info/PKG-INFO
+src/raqm_core.egg-info/SOURCES.txt
+src/raqm_core.egg-info/dependency_links.txt
+src/raqm_core.egg-info/requires.txt
+src/raqm_core.egg-info/top_level.txt
+src/raqm_core/headers/__init__.py
+src/raqm_core/headers/easypaisa.py
+src/raqm_core/headers/jazzcash.py
+src/raqm_core/schemas/__init__.py
+src/raqm_core/schemas/easypaisa.py
+tests/test_easypaisa.py

raqm_core-0.1.0/src/raqm_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

raqm_core-0.1.0/src/raqm_core.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.28.1
+pydantic>=2.0

raqm_core-0.1.0/src/raqm_core.egg-info/top_level.txt

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

raqm_core-0.1.0/tests/test_easypaisa.py

@@ -0,0 +1,162 @@
+import httpx
+import pytest
+
+from src.raqm_core.easypaisa import EasyPaisa
+
+MA_SUCCESS_BODY = {
+    "orderId": "abc123",
+    "storeId": 43,
+    "transactionId": "253184",
+    "transactionDateTime": "11/08/2018 11:30 PM",
+    "responseCode": "0000",
+    "responseDesc": "SUCCESS",
+}
+
+OTC_SUCCESS_BODY = {
+    "orderId": "abc123",
+    "storeId": 43,
+    "transactionDateTime": "11/08/2021 11:30 PM",
+    "responseCode": "0000",
+    "responseDesc": "SUCCESS",
+    "paymentToken": "tok_abc123",
+    "paymentTokenExpiryDateTime": "12/08/2021 11:30 PM",
+}
+
+INQUIRE_SUCCESS_BODY = {
+    "orderId": "abc123",
+    "storeId": 43,
+    "transactionId": "253184",
+    "transactionDateTime": "11/08/2021 11:30 PM",
+    "responseCode": "0000",
+    "responseDesc": "SUCCESS",
+    "accountNum": "123456789",
+    "storeName": "Test Store",
+    "paymentToken": None,
+    "transactionStatus": "COMPLETED",
+    "transactionAmount": "1.23",
+    "paymentTokenExpiryDateTime": None,
+    "msisdn": "03458508726",
+    "paymentMode": "MA",
+}
+
+
+def make_client(response_body: dict) -> httpx.AsyncClient:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status_code=200, json=response_body)
+
+    return httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+
+def make_ep(response_body: dict) -> EasyPaisa:
+    return EasyPaisa(
+        store_id="43",
+        username="admin",
+        password="123",
+        sandbox=True,
+        client=make_client(response_body),
+    )
+
+
+class TestPayViaMA:
+    @pytest.mark.asyncio
+    async def test_success(self):
+        ep = make_ep(MA_SUCCESS_BODY)
+        result = await ep.pay_via_ma(
+            order_id="abc123",
+            amount="1.23",
+            email="test@example.com",
+            mobile_number="03458508726",
+        )
+        assert result.orderId == "abc123"
+        assert result.transactionId == "253184"
+        assert result.responseCode == "0000"
+
+    @pytest.mark.parametrize(
+        ("body", "expected_code"),
+        [
+            ({"responseCode": "0001", "responseDesc": "SYSTEM ERROR"}, "0001"),
+            ({"responseCode": "0006", "responseDesc": "INVALID STORE ID"}, "0006"),
+            ({"responseCode": "0010", "responseDesc": "INVALID CREDENTIALS"}, "0010"),
+        ],
+    )
+    @pytest.mark.asyncio
+    async def test_error_codes(self, body, expected_code):
+        payload = {**MA_SUCCESS_BODY, **body}
+        ep = make_ep(payload)
+        result = await ep.pay_via_ma(
+            order_id="abc123",
+            amount="1.23",
+            email="test@example.com",
+            mobile_number="03458508726",
+        )
+        assert result.responseCode == expected_code
+
+
+class TestPayViaOTC:
+    @pytest.mark.asyncio
+    async def test_success(self):
+        ep = make_ep(OTC_SUCCESS_BODY)
+        result = await ep.pay_via_otc(
+            order_id="abc123",
+            amount="1.23",
+            email="test@example.com",
+            msisdn="03458508726",
+            token_expiry="11/12/2018 11:30 PM",
+        )
+        assert result.orderId == "abc123"
+        assert result.responseCode == "0000"
+        assert result.paymentToken == "tok_abc123"
+
+    @pytest.mark.parametrize(
+        ("body", "expected_code"),
+        [
+            ({"responseCode": "0001", "responseDesc": "SYSTEM ERROR"}, "0001"),
+            ({"responseCode": "0006", "responseDesc": "INVALID STORE ID"}, "0006"),
+            ({"responseCode": "0010", "responseDesc": "INVALID CREDENTIALS"}, "0010"),
+        ],
+    )
+    @pytest.mark.asyncio
+    async def test_error_codes(self, body, expected_code):
+        payload = {**OTC_SUCCESS_BODY, **body}
+        ep = make_ep(payload)
+        result = await ep.pay_via_otc(
+            order_id="abc123",
+            amount="1.23",
+            email="test@example.com",
+            msisdn="03458508726",
+            token_expiry="11/12/2018 11:30 PM",
+        )
+        assert result.responseCode == expected_code
+
+
+class TestInquireTransaction:
+    @pytest.mark.asyncio
+    async def test_success(self):
+        ep = make_ep(INQUIRE_SUCCESS_BODY)
+        result = await ep.inquire_transaction_status(
+            order_id="abc123", account_number="123456789"
+        )
+        assert result.orderId == "abc123"
+        assert result.responseCode == "0000"
+        assert result.transactionStatus == "COMPLETED"
+        assert result.accountNum == "123456789"
+        assert result.storeName == "Test Store"
+        assert result.msisdn == "03458508726"
+        assert result.paymentMode == "MA"
+
+    @pytest.mark.parametrize(
+        ("body", "expected_code"),
+        [
+            ({"responseCode": "0001", "responseDesc": "SYSTEM ERROR"}, "0001"),
+            ({"responseCode": "0006", "responseDesc": "INVALID STORE ID"}, "0006"),
+            ({"responseCode": "0010", "responseDesc": "INVALID CREDENTIALS"}, "0010"),
+        ],
+    )
+    @pytest.mark.asyncio
+    async def test_error_codes(self, body, expected_code):
+        payload = {**INQUIRE_SUCCESS_BODY, **body}
+        ep = make_ep(payload)
+        result = await ep.inquire_transaction_status(
+            order_id="abc123", account_number="123456789"
+        )
+        assert result.responseCode == expected_code