fastaar-python 1.0.3__tar.gz

fastaar_python-1.0.3/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: fastaar-python
+Version: 1.0.3
+Summary: Python SDK for the Fastaar payment gateway — accept bKash & Nagad payments in Bangladesh.
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# Fastaar Python SDK
+
+Accept bKash & Nagad payments on any Python website or application via [Fastaar](https://fastaar.com).
+
+This is a zero-dependency SDK utilizing Python's standard library.
+
+## Install
+
+Install the package via `pip` (or configure it in your `requirements.txt` / `pyproject.toml`):
+
+```bash
+pip install fastaar-python
+```
+
+## Create a payment & redirect to checkout
+
+Here is an example using a generic Python web application:
+
+```python
+import os
+from fastaar import FastaarClient
+
+fastaar = FastaarClient(api_key=os.getenv('FASTAAR_API_KEY'))  # fk_live_... or fk_test_...
+
+# The key must have the `payments:write` ability (and not be expired) or this
+# call returns a 403 `ability_denied` / 401 `authentication_error` error.
+payment = fastaar.create_payment({
+    'amount': 1250,
+    'invoice_number': 'ORDER-42',                         # required — your order reference
+    'customer_id': customer['id'] if customer else None, # optional — attach an existing customer
+    'success_url': 'https://shop.example.com/thanks', # optional, customer returns here
+    'cancel_url': 'https://shop.example.com/cart',    # optional
+})
+
+# Redirect the customer to checkout
+checkout_url = payment['checkout_url']
+print(f"Redirecting customer to: {checkout_url}")
+```
+
+`invoice_number` is idempotent: if a payment already exists for it and hasn't reached `failed`
+or `expired`, creating another one raises a `FastaarException` with error type
+`duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — so a dropped connection
+never double-charges. Use `find_by_invoice_number()` to look the existing payment up rather than
+retrying blindly.
+
+## Confirm the order from a webhook
+
+Verify the signature header to ensure webhook security:
+
+```python
+import os
+from fastaar import WebhookSignature, FastaarException
+
+# Get raw request body as bytes/string and signature header from request
+raw_body = request.body  # must be the raw string or bytes of the request body
+signature = request.headers.get('X-Fastaar-Signature', '')
+
+secret = os.getenv('FASTAAR_WEBHOOK_SECRET')
+
+if not WebhookSignature.verify(secret, raw_body, signature):
+    # Signature verification failed
+    return "Invalid signature", 400
+
+# Parse the event
+event = request.json()
+
+if event['event'] == 'payment.completed':
+    order_id = event['data']['invoice_number']
+    payment_id = event['data']['id']
+    # Mark the order as paid idempotently using the payment_id as key
+    print(f"Payment completed: {payment_id} for invoice {order_id}")
+
+return "OK", 200
+```
+
+## Other payment calls
+
+```python
+# Retrieve one payment by its ID (e.g. "01jxyz...")
+payment = fastaar.get_payment('01jxyz...')
+
+# Look up most recent payment by your reference
+payment = fastaar.find_by_invoice_number('ORDER-42')
+
+# List payments
+payments = fastaar.list_payments(params={'status': 'completed'})
+
+# Refund a completed (or partially refunded) payment
+payment = fastaar.refund_payment('01jxyz...')          # refund the full remaining balance
+payment = fastaar.refund_payment('01jxyz...', 200)     # or refund only part of it
+refunds = fastaar.list_refunds('01jxyz...')            # full refund history, newest first
+```
+
+## Customers
+
+Store customer records to attach them to payments collected via payment links.
+
+```python
+# Create a customer — name and phone are required
+customer = fastaar.create_customer({
+    'name':    'Rahim Uddin',
+    'phone':   '01712345678',
+    'email':   'rahim@example.com',   # optional
+    'address': 'Dhaka, Bangladesh',   # optional
+    'notes':   'VIP customer',        # optional
+})
+
+# Retrieve, update, list
+customer  = fastaar.get_customer(customer['id'])
+customer  = fastaar.update_customer(customer['id'], {'name': 'Rahim Ahmed'})
+customers = fastaar.list_customers({'email': 'rahim@example.com'})
+```
+
+## Error Handling
+
+Errors raise `fastaar.FastaarException` with `error_type` (e.g. `authentication_error`, `subscription_required`, `transaction_limit_reached`, `connection_error`) and `status_code`.
+
+```python
+from fastaar import FastaarException
+
+try:
+    payment = fastaar.create_payment({'amount': 100, 'invoice_number': 'ORDER-42'})
+except FastaarException as e:
+    print(f"API Error: {e}")
+    print(f"Type: {e.error_type}")
+    print(f"Status Code: {e.status_code}")
+```
+
+## Test mode
+
+Use an `fk_test_` key: payments auto-complete on the checkout page without real money, and webhooks fire exactly like production with `"livemode": false`.

fastaar_python-1.0.3/README.md

@@ -0,0 +1,131 @@
+# Fastaar Python SDK
+
+Accept bKash & Nagad payments on any Python website or application via [Fastaar](https://fastaar.com).
+
+This is a zero-dependency SDK utilizing Python's standard library.
+
+## Install
+
+Install the package via `pip` (or configure it in your `requirements.txt` / `pyproject.toml`):
+
+```bash
+pip install fastaar-python
+```
+
+## Create a payment & redirect to checkout
+
+Here is an example using a generic Python web application:
+
+```python
+import os
+from fastaar import FastaarClient
+
+fastaar = FastaarClient(api_key=os.getenv('FASTAAR_API_KEY'))  # fk_live_... or fk_test_...
+
+# The key must have the `payments:write` ability (and not be expired) or this
+# call returns a 403 `ability_denied` / 401 `authentication_error` error.
+payment = fastaar.create_payment({
+    'amount': 1250,
+    'invoice_number': 'ORDER-42',                         # required — your order reference
+    'customer_id': customer['id'] if customer else None, # optional — attach an existing customer
+    'success_url': 'https://shop.example.com/thanks', # optional, customer returns here
+    'cancel_url': 'https://shop.example.com/cart',    # optional
+})
+
+# Redirect the customer to checkout
+checkout_url = payment['checkout_url']
+print(f"Redirecting customer to: {checkout_url}")
+```
+
+`invoice_number` is idempotent: if a payment already exists for it and hasn't reached `failed`
+or `expired`, creating another one raises a `FastaarException` with error type
+`duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — so a dropped connection
+never double-charges. Use `find_by_invoice_number()` to look the existing payment up rather than
+retrying blindly.
+
+## Confirm the order from a webhook
+
+Verify the signature header to ensure webhook security:
+
+```python
+import os
+from fastaar import WebhookSignature, FastaarException
+
+# Get raw request body as bytes/string and signature header from request
+raw_body = request.body  # must be the raw string or bytes of the request body
+signature = request.headers.get('X-Fastaar-Signature', '')
+
+secret = os.getenv('FASTAAR_WEBHOOK_SECRET')
+
+if not WebhookSignature.verify(secret, raw_body, signature):
+    # Signature verification failed
+    return "Invalid signature", 400
+
+# Parse the event
+event = request.json()
+
+if event['event'] == 'payment.completed':
+    order_id = event['data']['invoice_number']
+    payment_id = event['data']['id']
+    # Mark the order as paid idempotently using the payment_id as key
+    print(f"Payment completed: {payment_id} for invoice {order_id}")
+
+return "OK", 200
+```
+
+## Other payment calls
+
+```python
+# Retrieve one payment by its ID (e.g. "01jxyz...")
+payment = fastaar.get_payment('01jxyz...')
+
+# Look up most recent payment by your reference
+payment = fastaar.find_by_invoice_number('ORDER-42')
+
+# List payments
+payments = fastaar.list_payments(params={'status': 'completed'})
+
+# Refund a completed (or partially refunded) payment
+payment = fastaar.refund_payment('01jxyz...')          # refund the full remaining balance
+payment = fastaar.refund_payment('01jxyz...', 200)     # or refund only part of it
+refunds = fastaar.list_refunds('01jxyz...')            # full refund history, newest first
+```
+
+## Customers
+
+Store customer records to attach them to payments collected via payment links.
+
+```python
+# Create a customer — name and phone are required
+customer = fastaar.create_customer({
+    'name':    'Rahim Uddin',
+    'phone':   '01712345678',
+    'email':   'rahim@example.com',   # optional
+    'address': 'Dhaka, Bangladesh',   # optional
+    'notes':   'VIP customer',        # optional
+})
+
+# Retrieve, update, list
+customer  = fastaar.get_customer(customer['id'])
+customer  = fastaar.update_customer(customer['id'], {'name': 'Rahim Ahmed'})
+customers = fastaar.list_customers({'email': 'rahim@example.com'})
+```
+
+## Error Handling
+
+Errors raise `fastaar.FastaarException` with `error_type` (e.g. `authentication_error`, `subscription_required`, `transaction_limit_reached`, `connection_error`) and `status_code`.
+
+```python
+from fastaar import FastaarException
+
+try:
+    payment = fastaar.create_payment({'amount': 100, 'invoice_number': 'ORDER-42'})
+except FastaarException as e:
+    print(f"API Error: {e}")
+    print(f"Type: {e.error_type}")
+    print(f"Status Code: {e.status_code}")
+```
+
+## Test mode
+
+Use an `fk_test_` key: payments auto-complete on the checkout page without real money, and webhooks fire exactly like production with `"livemode": false`.

fastaar_python-1.0.3/fastaar/__init__.py

@@ -0,0 +1,5 @@
+from fastaar.client import FastaarClient
+from fastaar.exceptions import FastaarException
+from fastaar.signature import WebhookSignature
+
+__all__ = ["FastaarClient", "FastaarException", "WebhookSignature"]

fastaar_python-1.0.3/fastaar/client.py

@@ -0,0 +1,239 @@
+import json
+import urllib.parse
+import urllib.request
+from urllib.error import HTTPError, URLError
+from typing import Any, Dict, List, Optional, Union
+
+from fastaar.exceptions import FastaarException
+
+BASE_URL = "https://fastaar.com"
+
+
+class FastaarClient:
+    def __init__(
+        self,
+        api_key: str,
+        timeout_seconds: int = 15,
+    ) -> None:
+        """
+        Initialize the Fastaar client.
+
+        Args:
+            api_key: Your Fastaar API key (e.g. fk_live_... or fk_test_...)
+            timeout_seconds: Connection and read timeout in seconds
+        """
+        self.api_key = api_key
+        self.timeout_seconds = timeout_seconds
+
+    # -------------------------------------------------------------------------
+    # Payments
+    # -------------------------------------------------------------------------
+
+    def create_payment(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create a payment intent.
+
+        Reusing the same `invoice_number` while a previous payment for it is still
+        active (not `failed`/`expired`) raises a FastaarException with error type
+        `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — look
+        the existing payment up with `find_by_invoice_number()` rather than retrying
+        blindly. Supply `success_url`/`cancel_url` to return the customer to your site
+        after checkout; Fastaar appends `payment_id` (and `invoice_number`) to them.
+
+        Args:
+            params: Dictionary containing:
+                - amount: int|float|str (required)
+                - invoice_number: str (required)
+                - customer_id: int (optional) - an existing customer belonging to your merchant account
+                - success_url: str (optional)
+                - cancel_url: str (optional)
+                - metadata: dict (optional)
+
+        Returns:
+            The payment object dictionary, including `id`, `status`, and `checkout_url`.
+        """
+        result = self._request("POST", "/api/v1/payments", body=params)
+        if not isinstance(result, dict):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    def get_payment(self, payment_id: str) -> Dict[str, Any]:
+        """
+        Retrieve a payment by its reference (the `id` returned at creation).
+        """
+        encoded_id = urllib.parse.quote(payment_id, safe="")
+        result = self._request("GET", f"/api/v1/payments/{encoded_id}")
+        if not isinstance(result, dict):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    def list_payments(self, params: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+        """
+        List payments, newest first.
+
+        Args:
+            params: Dictionary containing optional filters:
+                - status: str (optional)
+                - invoice_number: str (optional)
+                - per_page: int (optional)
+                - page: int (optional)
+        """
+        if params:
+            query = "?" + urllib.parse.urlencode(params)
+        else:
+            query = ""
+
+        result = self._request("GET", f"/api/v1/payments{query}")
+        if not isinstance(result, list):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    def find_by_invoice_number(self, invoice_number: str) -> Optional[Dict[str, Any]]:
+        """
+        Find the most recent payment for one of your invoice numbers, or None if none.
+        """
+        payments = self.list_payments({"invoice_number": invoice_number})
+        return payments[0] if payments else None
+
+    def refund_payment(self, payment_id: str, amount: Optional[float] = None) -> Dict[str, Any]:
+        """
+        Refund a payment, in full or in part. Only payments with status `completed` or
+        `partially_refunded` can be refunded. Pass an amount to refund only part of the
+        remaining balance; omit it to refund whatever is still refundable.
+
+        Returns:
+            The updated payment object. `status` is `refunded` once fully refunded, or
+            `partially_refunded` if some balance remains.
+
+        Raises:
+            FastaarException: if the payment is not in a refundable state, or the amount
+                exceeds the remaining refundable balance.
+        """
+        encoded_id = urllib.parse.quote(payment_id, safe="")
+        body = {"amount": amount} if amount is not None else None
+        result = self._request("POST", f"/api/v1/payments/{encoded_id}/refund", body=body)
+        if not isinstance(result, dict):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    def list_refunds(self, payment_id: str) -> List[Dict[str, Any]]:
+        """
+        List a payment's refund history, newest first — one entry per refund call, even
+        across several partial refunds.
+        """
+        encoded_id = urllib.parse.quote(payment_id, safe="")
+        result = self._request("GET", f"/api/v1/payments/{encoded_id}/refunds")
+        if not isinstance(result, list):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    # -------------------------------------------------------------------------
+    # Customers
+    # -------------------------------------------------------------------------
+
+    def list_customers(self, params: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+        """
+        List customers, newest first.
+
+        Args:
+            params: Optional filters — email, phone, per_page, page.
+        """
+        query = "?" + urllib.parse.urlencode(params) if params else ""
+        result = self._request("GET", f"/api/v1/customers{query}")
+        if not isinstance(result, list):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    def create_customer(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create a customer.
+
+        Args:
+            params: name (required), phone (required), email, address, notes.
+        """
+        result = self._request("POST", "/api/v1/customers", body=params)
+        if not isinstance(result, dict):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    def get_customer(self, customer_id: int) -> Dict[str, Any]:
+        """Retrieve a customer by ID."""
+        result = self._request("GET", f"/api/v1/customers/{customer_id}")
+        if not isinstance(result, dict):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    def update_customer(self, customer_id: int, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Update a customer (partial — only sent fields are changed)."""
+        result = self._request("PATCH", f"/api/v1/customers/{customer_id}", body=params)
+        if not isinstance(result, dict):
+            raise FastaarException("Fastaar API returned an unexpected response format.", "api_error")
+        return result
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+        url = BASE_URL + path
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+        }
+
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout_seconds) as response:
+                status_code = response.getcode()
+                response_body = response.read().decode("utf-8")
+        except HTTPError as e:
+            status_code = e.code
+            try:
+                response_body = e.read().decode("utf-8")
+            except Exception:
+                response_body = ""
+        except (URLError, Exception) as e:
+            # Check if reason is present
+            reason = getattr(e, "reason", str(e))
+            raise FastaarException(
+                message=f"Could not reach the Fastaar API: {reason}",
+                error_type="connection_error",
+                status_code=0,
+            )
+
+        try:
+            decoded = json.loads(response_body)
+        except json.JSONDecodeError:
+            decoded = None
+
+        if status_code >= 400 or not isinstance(decoded, (dict, list)):
+            error_message = None
+            error_type = "api_error"
+
+            if isinstance(decoded, dict):
+                error_details = decoded.get("error", decoded)
+                if isinstance(error_details, dict):
+                    error_message = error_details.get("message")
+                    error_type = error_details.get("type", "api_error")
+
+            if not error_message:
+                error_message = f"Fastaar API returned HTTP {status_code}."
+
+            raise FastaarException(
+                message=error_message,
+                error_type=error_type,
+                status_code=status_code,
+            )
+
+        # In case Fastaar envelopes data, return decoded['data'] if it exists, otherwise full decoded
+        if isinstance(decoded, dict) and "data" in decoded:
+            return decoded["data"]
+        return decoded

fastaar_python-1.0.3/fastaar/exceptions.py

@@ -0,0 +1,16 @@
+class FastaarException(Exception):
+    """
+    Exception raised for errors in the Fastaar SDK.
+
+    Attributes:
+        message -- explanation of the error
+        error_type -- stable API error code, e.g. "authentication_error",
+                      "subscription_required", "transaction_limit_reached",
+                      "connection_error", or "api_error"
+        status_code -- HTTP status code returned by the API (0 if connection error)
+    """
+
+    def __init__(self, message: str, error_type: str = "api_error", status_code: int = 0):
+        super().__init__(message)
+        self.error_type = error_type
+        self.status_code = status_code

fastaar_python-1.0.3/fastaar/signature.py

@@ -0,0 +1,53 @@
+import hashlib
+import hmac
+import re
+import time
+from typing import Union
+
+
+class WebhookSignature:
+    @staticmethod
+    def verify(
+        secret: Union[str, bytes],
+        raw_body: Union[str, bytes],
+        signature_header: str,
+        tolerance_seconds: int = 300,
+    ) -> bool:
+        """
+        Verify the X-Fastaar-Signature header (`t=<ts>,v1=<hmac>`) against
+        the raw request body using your merchant webhook secret.
+        """
+        if not signature_header or not secret:
+            return False
+
+        # Match signature header pattern: t=<timestamp>,v1=<hmac-sha256>
+        match = re.match(r"^t=(?P<t>\d+),v1=(?P<v1>[a-f0-9]{64})$", signature_header)
+        if not match:
+            return False
+
+        try:
+            timestamp = int(match.group("t"))
+        except ValueError:
+            return False
+
+        # Check timestamp tolerance
+        current_time = int(time.time())
+        if abs(current_time - timestamp) > tolerance_seconds:
+            return False
+
+        # Ensure raw_body is a string
+        if isinstance(raw_body, bytes):
+            raw_body = raw_body.decode("utf-8")
+
+        # Prepare secret and message payload
+        secret_bytes = secret.encode("utf-8") if isinstance(secret, str) else secret
+        payload_bytes = f"{timestamp}.{raw_body}".encode("utf-8")
+
+        # Generate expected signature
+        expected = hmac.new(
+            secret_bytes,
+            payload_bytes,
+            hashlib.sha256
+        ).hexdigest()
+
+        return hmac.compare_digest(expected, match.group("v1"))

fastaar_python-1.0.3/fastaar_python.egg-info/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: fastaar-python
+Version: 1.0.3
+Summary: Python SDK for the Fastaar payment gateway — accept bKash & Nagad payments in Bangladesh.
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# Fastaar Python SDK
+
+Accept bKash & Nagad payments on any Python website or application via [Fastaar](https://fastaar.com).
+
+This is a zero-dependency SDK utilizing Python's standard library.
+
+## Install
+
+Install the package via `pip` (or configure it in your `requirements.txt` / `pyproject.toml`):
+
+```bash
+pip install fastaar-python
+```
+
+## Create a payment & redirect to checkout
+
+Here is an example using a generic Python web application:
+
+```python
+import os
+from fastaar import FastaarClient
+
+fastaar = FastaarClient(api_key=os.getenv('FASTAAR_API_KEY'))  # fk_live_... or fk_test_...
+
+# The key must have the `payments:write` ability (and not be expired) or this
+# call returns a 403 `ability_denied` / 401 `authentication_error` error.
+payment = fastaar.create_payment({
+    'amount': 1250,
+    'invoice_number': 'ORDER-42',                         # required — your order reference
+    'customer_id': customer['id'] if customer else None, # optional — attach an existing customer
+    'success_url': 'https://shop.example.com/thanks', # optional, customer returns here
+    'cancel_url': 'https://shop.example.com/cart',    # optional
+})
+
+# Redirect the customer to checkout
+checkout_url = payment['checkout_url']
+print(f"Redirecting customer to: {checkout_url}")
+```
+
+`invoice_number` is idempotent: if a payment already exists for it and hasn't reached `failed`
+or `expired`, creating another one raises a `FastaarException` with error type
+`duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — so a dropped connection
+never double-charges. Use `find_by_invoice_number()` to look the existing payment up rather than
+retrying blindly.
+
+## Confirm the order from a webhook
+
+Verify the signature header to ensure webhook security:
+
+```python
+import os
+from fastaar import WebhookSignature, FastaarException
+
+# Get raw request body as bytes/string and signature header from request
+raw_body = request.body  # must be the raw string or bytes of the request body
+signature = request.headers.get('X-Fastaar-Signature', '')
+
+secret = os.getenv('FASTAAR_WEBHOOK_SECRET')
+
+if not WebhookSignature.verify(secret, raw_body, signature):
+    # Signature verification failed
+    return "Invalid signature", 400
+
+# Parse the event
+event = request.json()
+
+if event['event'] == 'payment.completed':
+    order_id = event['data']['invoice_number']
+    payment_id = event['data']['id']
+    # Mark the order as paid idempotently using the payment_id as key
+    print(f"Payment completed: {payment_id} for invoice {order_id}")
+
+return "OK", 200
+```
+
+## Other payment calls
+
+```python
+# Retrieve one payment by its ID (e.g. "01jxyz...")
+payment = fastaar.get_payment('01jxyz...')
+
+# Look up most recent payment by your reference
+payment = fastaar.find_by_invoice_number('ORDER-42')
+
+# List payments
+payments = fastaar.list_payments(params={'status': 'completed'})
+
+# Refund a completed (or partially refunded) payment
+payment = fastaar.refund_payment('01jxyz...')          # refund the full remaining balance
+payment = fastaar.refund_payment('01jxyz...', 200)     # or refund only part of it
+refunds = fastaar.list_refunds('01jxyz...')            # full refund history, newest first
+```
+
+## Customers
+
+Store customer records to attach them to payments collected via payment links.
+
+```python
+# Create a customer — name and phone are required
+customer = fastaar.create_customer({
+    'name':    'Rahim Uddin',
+    'phone':   '01712345678',
+    'email':   'rahim@example.com',   # optional
+    'address': 'Dhaka, Bangladesh',   # optional
+    'notes':   'VIP customer',        # optional
+})
+
+# Retrieve, update, list
+customer  = fastaar.get_customer(customer['id'])
+customer  = fastaar.update_customer(customer['id'], {'name': 'Rahim Ahmed'})
+customers = fastaar.list_customers({'email': 'rahim@example.com'})
+```
+
+## Error Handling
+
+Errors raise `fastaar.FastaarException` with `error_type` (e.g. `authentication_error`, `subscription_required`, `transaction_limit_reached`, `connection_error`) and `status_code`.
+
+```python
+from fastaar import FastaarException
+
+try:
+    payment = fastaar.create_payment({'amount': 100, 'invoice_number': 'ORDER-42'})
+except FastaarException as e:
+    print(f"API Error: {e}")
+    print(f"Type: {e.error_type}")
+    print(f"Status Code: {e.status_code}")
+```
+
+## Test mode
+
+Use an `fk_test_` key: payments auto-complete on the checkout page without real money, and webhooks fire exactly like production with `"livemode": false`.

fastaar_python-1.0.3/fastaar_python.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+fastaar/__init__.py
+fastaar/client.py
+fastaar/exceptions.py
+fastaar/signature.py
+fastaar_python.egg-info/PKG-INFO
+fastaar_python.egg-info/SOURCES.txt
+fastaar_python.egg-info/dependency_links.txt
+fastaar_python.egg-info/requires.txt
+fastaar_python.egg-info/top_level.txt
+tests/test_client.py
+tests/test_signature.py

fastaar_python-1.0.3/fastaar_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastaar_python-1.0.3/fastaar_python.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7.0

fastaar_python-1.0.3/fastaar_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastaar

fastaar_python-1.0.3/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastaar-python"
+version = "1.0.3"
+description = "Python SDK for the Fastaar payment gateway — accept bKash & Nagad payments in Bangladesh."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["fastaar*"]

fastaar_python-1.0.3/setup.cfg

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

fastaar_python-1.0.3/tests/test_client.py

@@ -0,0 +1,164 @@
+import io
+import json
+import unittest
+from urllib.error import HTTPError, URLError
+from unittest.mock import patch, MagicMock
+
+from fastaar import FastaarClient, FastaarException
+
+
+class TestFastaarClient(unittest.TestCase):
+    def setUp(self) -> None:
+        self.api_key = "fk_test_12345"
+        self.client = FastaarClient(api_key=self.api_key)
+
+    def _mock_response(self, status_code: int, body: str) -> MagicMock:
+        mock_resp = MagicMock()
+        mock_resp.getcode.return_value = status_code
+        mock_resp.read.return_value = body.encode("utf-8")
+        mock_resp.__enter__.return_value = mock_resp
+        return mock_resp
+
+    @patch("urllib.request.urlopen")
+    def test_create_payment_success(self, mock_urlopen: MagicMock) -> None:
+        response_data = {
+            "data": {
+                "id": "pay_01jxyz",
+                "status": "pending",
+                "amount": 1250,
+                "invoice_number": "ORDER-42",
+                "checkout_url": "https://fastaar.test/checkout/01jxyz"
+            }
+        }
+        mock_urlopen.return_value = self._mock_response(201, json.dumps(response_data))
+
+        params = {
+            "amount": 1250,
+            "invoice_number": "ORDER-42",
+            "success_url": "https://shop.example.com/thanks"
+        }
+        payment = self.client.create_payment(params)
+
+        # Verify response matches
+        self.assertEqual(payment["id"], "pay_01jxyz")
+        self.assertEqual(payment["checkout_url"], "https://fastaar.test/checkout/01jxyz")
+
+        # Verify request parameters
+        args, kwargs = mock_urlopen.call_args
+        req = args[0]
+        self.assertEqual(req.get_full_url(), "https://fastaar.com/api/v1/payments")
+        self.assertEqual(req.method, "POST")
+        self.assertEqual(req.headers["Authorization"], f"Bearer {self.api_key}")
+        self.assertEqual(req.headers["Content-type"], "application/json")
+        self.assertEqual(req.headers["Accept"], "application/json")
+        self.assertEqual(json.loads(req.data.decode("utf-8")), params)
+
+    @patch("urllib.request.urlopen")
+    def test_get_payment_success(self, mock_urlopen: MagicMock) -> None:
+        response_data = {
+            "data": {
+                "id": "pay/01jxyz",  # contains a slash to test encoding
+                "status": "completed"
+            }
+        }
+        mock_urlopen.return_value = self._mock_response(200, json.dumps(response_data))
+
+        payment = self.client.get_payment("pay/01jxyz")
+
+        self.assertEqual(payment["id"], "pay/01jxyz")
+        self.assertEqual(payment["status"], "completed")
+
+        args, _ = mock_urlopen.call_args
+        req = args[0]
+        # pay/01jxyz should be URL encoded as pay%2F01jxyz
+        self.assertEqual(req.get_full_url(), "https://fastaar.com/api/v1/payments/pay%2F01jxyz")
+        self.assertEqual(req.method, "GET")
+
+    @patch("urllib.request.urlopen")
+    def test_list_payments_success(self, mock_urlopen: MagicMock) -> None:
+        response_data = {
+            "data": [
+                {"id": "1", "status": "completed"},
+                {"id": "2", "status": "pending"}
+            ]
+        }
+        mock_urlopen.return_value = self._mock_response(200, json.dumps(response_data))
+
+        payments = self.client.list_payments({"status": "completed", "page": 2})
+
+        self.assertEqual(len(payments), 2)
+        self.assertEqual(payments[0]["id"], "1")
+
+        args, _ = mock_urlopen.call_args
+        req = args[0]
+        # Query parameters should be correctly encoded
+        self.assertIn("https://fastaar.com/api/v1/payments?", req.get_full_url())
+        self.assertIn("status=completed", req.get_full_url())
+        self.assertIn("page=2", req.get_full_url())
+        self.assertEqual(req.method, "GET")
+
+    @patch("urllib.request.urlopen")
+    def test_find_by_invoice_number_found(self, mock_urlopen: MagicMock) -> None:
+        response_data = {
+            "data": [
+                {"id": "pay_01jxyz", "invoice_number": "ORDER-42"}
+            ]
+        }
+        mock_urlopen.return_value = self._mock_response(200, json.dumps(response_data))
+
+        payment = self.client.find_by_invoice_number("ORDER-42")
+
+        self.assertIsNotNone(payment)
+        self.assertEqual(payment["id"], "pay_01jxyz")
+
+    @patch("urllib.request.urlopen")
+    def test_find_by_invoice_number_not_found(self, mock_urlopen: MagicMock) -> None:
+        response_data = {"data": []}
+        mock_urlopen.return_value = self._mock_response(200, json.dumps(response_data))
+
+        payment = self.client.find_by_invoice_number("ORDER-42")
+
+        self.assertIsNull = self.assertIsNone(payment)
+
+    @patch("urllib.request.urlopen")
+    def test_request_error_400(self, mock_urlopen: MagicMock) -> None:
+        error_data = {
+            "error": {
+                "message": "The amount field is required.",
+                "type": "validation_error"
+            }
+        }
+        # Simulate HTTP Error in urlopen
+        fp = io.BytesIO(json.dumps(error_data).encode("utf-8"))
+        mock_urlopen.side_effect = HTTPError("url", 400, "Bad Request", {}, fp)
+
+        with self.assertRaises(FastaarException) as context:
+            self.client.create_payment({})
+
+        self.assertEqual(context.exception.status_code, 400)
+        self.assertEqual(context.exception.error_type, "validation_error")
+        self.assertEqual(str(context.exception), "The amount field is required.")
+
+    @patch("urllib.request.urlopen")
+    def test_request_error_generic_500(self, mock_urlopen: MagicMock) -> None:
+        # Simulate generic server error without JSON format
+        fp = io.BytesIO(b"Internal Server Error")
+        mock_urlopen.side_effect = HTTPError("url", 500, "Internal Server Error", {}, fp)
+
+        with self.assertRaises(FastaarException) as context:
+            self.client.create_payment({})
+
+        self.assertEqual(context.exception.status_code, 500)
+        self.assertEqual(context.exception.error_type, "api_error")
+        self.assertEqual(str(context.exception), "Fastaar API returned HTTP 500.")
+
+    @patch("urllib.request.urlopen")
+    def test_request_connection_error(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.side_effect = URLError("connection refused")
+
+        with self.assertRaises(FastaarException) as context:
+            self.client.create_payment({})
+
+        self.assertEqual(context.exception.status_code, 0)
+        self.assertEqual(context.exception.error_type, "connection_error")
+        self.assertIn("connection refused", str(context.exception))

fastaar_python-1.0.3/tests/test_signature.py

@@ -0,0 +1,82 @@
+import hashlib
+import hmac
+import time
+import unittest
+
+from fastaar.signature import WebhookSignature
+
+
+class TestWebhookSignature(unittest.TestCase):
+    def setUp(self) -> None:
+        self.secret = "super-secret-key"
+        self.raw_body = '{"event":"payment.completed","data":{"invoice_number":"ORDER-42"}}'
+        self.timestamp = int(time.time())
+
+    def _generate_signature(self, secret: str, timestamp: int, body: str) -> str:
+        payload = f"{timestamp}.{body}".encode("utf-8")
+        h = hmac.new(secret.encode("utf-8"), payload, hashlib.sha256)
+        return f"t={timestamp},v1={h.hexdigest()}"
+
+    def test_verify_valid_signature_string(self) -> None:
+        sig = self._generate_signature(self.secret, self.timestamp, self.raw_body)
+        self.assertTrue(
+            WebhookSignature.verify(self.secret, self.raw_body, sig)
+        )
+
+    def test_verify_valid_signature_bytes(self) -> None:
+        sig = self._generate_signature(self.secret, self.timestamp, self.raw_body)
+        # Verify it works when raw_body is bytes
+        self.assertTrue(
+            WebhookSignature.verify(self.secret, self.raw_body.encode("utf-8"), sig)
+        )
+        # Verify it works when secret is bytes
+        self.assertTrue(
+            WebhookSignature.verify(self.secret.encode("utf-8"), self.raw_body, sig)
+        )
+
+    def test_verify_invalid_secret(self) -> None:
+        sig = self._generate_signature(self.secret, self.timestamp, self.raw_body)
+        self.assertFalse(
+            WebhookSignature.verify("wrong-secret", self.raw_body, sig)
+        )
+
+    def test_verify_invalid_body(self) -> None:
+        sig = self._generate_signature(self.secret, self.timestamp, self.raw_body)
+        self.assertFalse(
+            WebhookSignature.verify(self.secret, "modified-body", sig)
+        )
+
+    def test_verify_expired_timestamp(self) -> None:
+        expired_ts = self.timestamp - 301
+        sig = self._generate_signature(self.secret, expired_ts, self.raw_body)
+        self.assertFalse(
+            WebhookSignature.verify(self.secret, self.raw_body, sig)
+        )
+
+    def test_verify_future_timestamp_within_tolerance(self) -> None:
+        future_ts = self.timestamp + 100
+        sig = self._generate_signature(self.secret, future_ts, self.raw_body)
+        self.assertTrue(
+            WebhookSignature.verify(self.secret, self.raw_body, sig)
+        )
+
+    def test_verify_future_timestamp_outside_tolerance(self) -> None:
+        future_ts = self.timestamp + 301
+        sig = self._generate_signature(self.secret, future_ts, self.raw_body)
+        self.assertFalse(
+            WebhookSignature.verify(self.secret, self.raw_body, sig)
+        )
+
+    def test_verify_invalid_signature_format(self) -> None:
+        self.assertFalse(
+            WebhookSignature.verify(self.secret, self.raw_body, "invalid-format")
+        )
+        self.assertFalse(
+            WebhookSignature.verify(self.secret, self.raw_body, f"t={self.timestamp}")
+        )
+        self.assertFalse(
+            WebhookSignature.verify(self.secret, self.raw_body, "t=abc,v1=abcdef")
+        )
+        self.assertFalse(
+            WebhookSignature.verify(self.secret, self.raw_body, "")
+        )