fastaar-python 1.0.3__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+fastaar/__init__.py,sha256=BBPMU-Yv3JQ-9e_wvP21MuvFaLMwcxLJI7Fom0CLXX4,205
+fastaar/client.py,sha256=ETxwyibVj3ighJVbLgf6MXlYMqeu9WJnJF2uNeqxqwU,9710
+fastaar/exceptions.py,sha256=uVOXg7oc5ictqRuTJOuvfVY1vQ5DEI6JFWwLBv6mr4g,657
+fastaar/signature.py,sha256=NAnXcjlmaG_jzGUIQnL4TMNUd4L5HwLWYSTw4v6SrFE,1568
+fastaar_python-1.0.3.dist-info/METADATA,sha256=sAMCJpcqhDbfwmCa8m76hCLy3GDHV7C7RdbcbBlnGio,4920
+fastaar_python-1.0.3.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+fastaar_python-1.0.3.dist-info/top_level.txt,sha256=DsGjqdIYVu85l7X2ZWZ-KbWlmlZ5-fRBWd5ar-yF2rM,8
+fastaar_python-1.0.3.dist-info/RECORD,,

fastaar_python-1.0.3.dist-info/WHEEL

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

fastaar_python-1.0.3.dist-info/top_level.txt

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