finswitz 1.0.0__tar.gz

finswitz-1.0.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: finswitz
+Version: 1.0.0
+Summary: Official Python SDK for the Finswitz API
+Author: Finswitz
+License: MIT
+Keywords: payments,fintech,finswitz,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Finswitz Python SDK
+
+Python client for the Finswitz API.
+
+## Installation
+
+The Python SDK is currently distributed as a source client. Add `finswitz.py` to your application package, then import `Finswitz`.
+
+When a package is published, this README should be updated with the package manager install command.
+
+## Requirements
+
+- Python 3.9 or newer
+- A Finswitz test or live secret key
+
+## Quick Start
+
+```python
+import os
+from finswitz import Finswitz
+
+client = Finswitz(api_key=os.environ["FINSWITZ_SECRET_KEY"])
+
+link = client.create_payment_link(
+    {
+        "amount": 5000,
+        "currency": "NGN",
+        "title": "Order #1234",
+        "email": "buyer@example.com",
+        "callback_url": "https://merchant.example/complete",
+    },
+    idempotency_key="order-1234-link",
+)
+
+print(link["checkoutUrl"])
+```
+
+## Custom Base URL
+
+```python
+client = Finswitz(
+    api_key=os.environ["FINSWITZ_SECRET_KEY"],
+    base_url="http://localhost:4000",
+)
+```
+
+## Payments
+
+```python
+client.transfer(
+    {
+        "amount": 5000,
+        "currency": "NGN",
+        "bank_code": "058",
+        "account_number": "0123456789",
+        "narration": "Vendor payout",
+    },
+    idempotency_key="transfer-001",
+)
+
+client.mobile_money(
+    {
+        "amount": 1500,
+        "currency": "GHS",
+        "phone": "+233501112222",
+        "country": "GH",
+    },
+    idempotency_key="momo-001",
+)
+
+transaction = client.get_transaction("reference")
+```
+
+## Dashboard JWT Helpers
+
+```python
+client = Finswitz(
+    api_key=os.environ["FINSWITZ_SECRET_KEY"],
+    dashboard_token=os.environ["FINSWITZ_DASHBOARD_TOKEN"],
+)
+
+client.update_webhooks(
+    {
+        "mode": "test",
+        "url": "https://merchant.example/webhooks/finswitz",
+    }
+)
+
+wallets = client.wallets()
+treasury = client.treasury()
+```
+
+## Collections
+
+```python
+collection = client.public_collection("school-fees")
+
+payment = client.pay_collection(
+    "school-fees",
+    {
+        "fullName": "Grace Johnson",
+        "email": "grace@example.com",
+        "amount": 10000,
+        "phone": "+2348012345678",
+    },
+)
+```
+
+## Error Handling
+
+```python
+from finswitz import FinswitzApiError
+
+try:
+    client.get_transaction("missing-reference")
+except FinswitzApiError as error:
+    print(error.status)
+    print(error.response)
+    raise
+```
+

finswitz-1.0.0/README.md

@@ -0,0 +1,121 @@
+# Finswitz Python SDK
+
+Python client for the Finswitz API.
+
+## Installation
+
+The Python SDK is currently distributed as a source client. Add `finswitz.py` to your application package, then import `Finswitz`.
+
+When a package is published, this README should be updated with the package manager install command.
+
+## Requirements
+
+- Python 3.9 or newer
+- A Finswitz test or live secret key
+
+## Quick Start
+
+```python
+import os
+from finswitz import Finswitz
+
+client = Finswitz(api_key=os.environ["FINSWITZ_SECRET_KEY"])
+
+link = client.create_payment_link(
+    {
+        "amount": 5000,
+        "currency": "NGN",
+        "title": "Order #1234",
+        "email": "buyer@example.com",
+        "callback_url": "https://merchant.example/complete",
+    },
+    idempotency_key="order-1234-link",
+)
+
+print(link["checkoutUrl"])
+```
+
+## Custom Base URL
+
+```python
+client = Finswitz(
+    api_key=os.environ["FINSWITZ_SECRET_KEY"],
+    base_url="http://localhost:4000",
+)
+```
+
+## Payments
+
+```python
+client.transfer(
+    {
+        "amount": 5000,
+        "currency": "NGN",
+        "bank_code": "058",
+        "account_number": "0123456789",
+        "narration": "Vendor payout",
+    },
+    idempotency_key="transfer-001",
+)
+
+client.mobile_money(
+    {
+        "amount": 1500,
+        "currency": "GHS",
+        "phone": "+233501112222",
+        "country": "GH",
+    },
+    idempotency_key="momo-001",
+)
+
+transaction = client.get_transaction("reference")
+```
+
+## Dashboard JWT Helpers
+
+```python
+client = Finswitz(
+    api_key=os.environ["FINSWITZ_SECRET_KEY"],
+    dashboard_token=os.environ["FINSWITZ_DASHBOARD_TOKEN"],
+)
+
+client.update_webhooks(
+    {
+        "mode": "test",
+        "url": "https://merchant.example/webhooks/finswitz",
+    }
+)
+
+wallets = client.wallets()
+treasury = client.treasury()
+```
+
+## Collections
+
+```python
+collection = client.public_collection("school-fees")
+
+payment = client.pay_collection(
+    "school-fees",
+    {
+        "fullName": "Grace Johnson",
+        "email": "grace@example.com",
+        "amount": 10000,
+        "phone": "+2348012345678",
+    },
+)
+```
+
+## Error Handling
+
+```python
+from finswitz import FinswitzApiError
+
+try:
+    client.get_transaction("missing-reference")
+except FinswitzApiError as error:
+    print(error.status)
+    print(error.response)
+    raise
+```
+

finswitz-1.0.0/finswitz.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: finswitz
+Version: 1.0.0
+Summary: Official Python SDK for the Finswitz API
+Author: Finswitz
+License: MIT
+Keywords: payments,fintech,finswitz,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Finswitz Python SDK
+
+Python client for the Finswitz API.
+
+## Installation
+
+The Python SDK is currently distributed as a source client. Add `finswitz.py` to your application package, then import `Finswitz`.
+
+When a package is published, this README should be updated with the package manager install command.
+
+## Requirements
+
+- Python 3.9 or newer
+- A Finswitz test or live secret key
+
+## Quick Start
+
+```python
+import os
+from finswitz import Finswitz
+
+client = Finswitz(api_key=os.environ["FINSWITZ_SECRET_KEY"])
+
+link = client.create_payment_link(
+    {
+        "amount": 5000,
+        "currency": "NGN",
+        "title": "Order #1234",
+        "email": "buyer@example.com",
+        "callback_url": "https://merchant.example/complete",
+    },
+    idempotency_key="order-1234-link",
+)
+
+print(link["checkoutUrl"])
+```
+
+## Custom Base URL
+
+```python
+client = Finswitz(
+    api_key=os.environ["FINSWITZ_SECRET_KEY"],
+    base_url="http://localhost:4000",
+)
+```
+
+## Payments
+
+```python
+client.transfer(
+    {
+        "amount": 5000,
+        "currency": "NGN",
+        "bank_code": "058",
+        "account_number": "0123456789",
+        "narration": "Vendor payout",
+    },
+    idempotency_key="transfer-001",
+)
+
+client.mobile_money(
+    {
+        "amount": 1500,
+        "currency": "GHS",
+        "phone": "+233501112222",
+        "country": "GH",
+    },
+    idempotency_key="momo-001",
+)
+
+transaction = client.get_transaction("reference")
+```
+
+## Dashboard JWT Helpers
+
+```python
+client = Finswitz(
+    api_key=os.environ["FINSWITZ_SECRET_KEY"],
+    dashboard_token=os.environ["FINSWITZ_DASHBOARD_TOKEN"],
+)
+
+client.update_webhooks(
+    {
+        "mode": "test",
+        "url": "https://merchant.example/webhooks/finswitz",
+    }
+)
+
+wallets = client.wallets()
+treasury = client.treasury()
+```
+
+## Collections
+
+```python
+collection = client.public_collection("school-fees")
+
+payment = client.pay_collection(
+    "school-fees",
+    {
+        "fullName": "Grace Johnson",
+        "email": "grace@example.com",
+        "amount": 10000,
+        "phone": "+2348012345678",
+    },
+)
+```
+
+## Error Handling
+
+```python
+from finswitz import FinswitzApiError
+
+try:
+    client.get_transaction("missing-reference")
+except FinswitzApiError as error:
+    print(error.status)
+    print(error.response)
+    raise
+```
+

finswitz-1.0.0/finswitz.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+finswitz.py
+pyproject.toml
+finswitz.egg-info/PKG-INFO
+finswitz.egg-info/SOURCES.txt
+finswitz.egg-info/dependency_links.txt
+finswitz.egg-info/top_level.txt

finswitz-1.0.0/finswitz.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

finswitz-1.0.0/finswitz.egg-info/top_level.txt

@@ -0,0 +1 @@
+finswitz

finswitz-1.0.0/finswitz.py

@@ -0,0 +1,200 @@
+import json
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+
+
+DEFAULT_BASE_URL = "https://api.finswitz.com"
+
+
+class FinswitzApiError(Exception):
+    def __init__(self, message, status=None, response=None):
+        super().__init__(message)
+        self.status = status
+        self.response = response
+
+
+class Finswitz:
+    def __init__(self, api_key=None, dashboard_token=None, base_url=DEFAULT_BASE_URL):
+        self.api_key = api_key
+        self.dashboard_token = dashboard_token
+        self.base_url = base_url.rstrip("/")
+
+    def request(self, method, path, body=None, query=None, idempotency_key=None, token_type="api", token=None):
+        bearer = token or (self.dashboard_token if token_type == "dashboard" else self.api_key)
+        if token_type != "none" and not bearer:
+            raise ValueError("Missing dashboard_token." if token_type == "dashboard" else "Missing api_key.")
+
+        url = self.base_url + path
+        if query:
+            clean_query = {key: value for key, value in query.items() if value is not None}
+            if clean_query:
+                url += "?" + urlencode(clean_query)
+
+        payload = None if body is None else json.dumps(body).encode("utf-8")
+        headers = {"Accept": "application/json"}
+        if token_type != "none":
+            headers["Authorization"] = "Bearer " + bearer
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        req = Request(url, data=payload, headers=headers, method=method)
+        try:
+            with urlopen(req, timeout=30) as res:
+                text = res.read().decode("utf-8")
+                return json.loads(text) if text else None
+        except HTTPError as err:
+            text = err.read().decode("utf-8")
+            data = json.loads(text) if text else None
+            message = data.get("error") if isinstance(data, dict) else None
+            raise FinswitzApiError(message or f"Finswitz API request failed with {err.code}", err.code, data)
+
+    def get(self, path, **kwargs):
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path, body=None, **kwargs):
+        return self.request("POST", path, body=body or {}, **kwargs)
+
+    def patch(self, path, body=None, **kwargs):
+        return self.request("PATCH", path, body=body or {}, **kwargs)
+
+    def transfer(self, payload, idempotency_key=None):
+        return self.post("/payments/transfer", payload, idempotency_key=idempotency_key)
+
+    def verify_account(self, payload):
+        return self.post("/payments/verify-account", payload)
+
+    def create_payment_link(self, payload, idempotency_key=None):
+        return self.post("/payments/payment-links", payload, idempotency_key=idempotency_key)
+
+    def mobile_money(self, payload, idempotency_key=None):
+        return self.post("/payments/mobile-money", payload, idempotency_key=idempotency_key)
+
+    def mock_charge(self, payload):
+        return self.post("/payments/mock/charge", payload)
+
+    def get_transaction(self, reference):
+        return self.get(f"/payments/{reference}")
+
+    def list_transactions(self, query=None):
+        return self.get("/payments", query=query)
+
+    def refund(self, reference, payload=None, idempotency_key=None):
+        return self.post(f"/payments/{reference}/refund", payload or {}, idempotency_key=idempotency_key)
+
+    def list_banks(self, query=None):
+        return self.get("/payments/banks", query=query)
+
+    def card_pricing(self):
+        return self.get("/cards/pricing")
+
+    def issue_card(self, payload, idempotency_key=None):
+        return self.post("/cards/issue", payload, idempotency_key=idempotency_key)
+
+    def list_cards(self, query=None):
+        return self.get("/cards", query=query)
+
+    def list_card_transactions(self, card_id, query=None):
+        return self.get(f"/cards/{card_id}/transactions", query=query)
+
+    def get_card_transaction(self, card_id, transaction_id):
+        return self.get(f"/cards/{card_id}/transactions/{transaction_id}")
+
+    def me(self):
+        return self.get("/developers/me", token_type="dashboard")
+
+    def list_api_keys(self):
+        return self.get("/developers/keys", token_type="dashboard")
+
+    def create_api_key(self, payload):
+        return self.post("/developers/keys", payload, token_type="dashboard")
+
+    def revoke_api_key(self, key_id):
+        return self.post(f"/developers/keys/{key_id}/revoke", {}, token_type="dashboard")
+
+    def update_webhooks(self, payload):
+        return self.request("PUT", "/developers/webhooks", body=payload, token_type="dashboard")
+
+    def list_webhook_logs(self, query=None):
+        return self.get("/developers/webhooks/logs", query=query, token_type="dashboard")
+
+    def simulate_webhook(self, payload):
+        return self.post("/developers/webhooks/simulate", payload, token_type="dashboard")
+
+    def wallets(self):
+        return self.get("/developers/wallets", token_type="dashboard")
+
+    def fund_wallet(self, payload):
+        return self.post("/developers/wallets/fund", payload, token_type="dashboard")
+
+    def wallet_funding_status(self, query=None):
+        return self.get("/developers/wallets/fund/status", query=query, token_type="dashboard")
+
+    def convert_wallet(self, payload):
+        return self.post("/developers/wallets/convert", payload, token_type="dashboard")
+
+    def treasury(self):
+        return self.get("/developers/treasury", token_type="dashboard")
+
+    def list_split_rules(self):
+        return self.get("/developers/treasury/split-rules", token_type="dashboard")
+
+    def create_split_rule(self, payload, idempotency_key=None):
+        return self.post("/developers/treasury/split-rules", payload, idempotency_key=idempotency_key, token_type="dashboard")
+
+    def update_split_rule(self, rule_id, payload):
+        return self.patch(f"/developers/treasury/split-rules/{rule_id}", payload, token_type="dashboard")
+
+    def list_escrow_holds(self):
+        return self.get("/developers/treasury/escrow", token_type="dashboard")
+
+    def create_escrow_hold(self, payload, idempotency_key=None):
+        return self.post("/developers/treasury/escrow", payload, idempotency_key=idempotency_key, token_type="dashboard")
+
+    def release_escrow_hold(self, hold_id, payload=None, idempotency_key=None):
+        return self.post(f"/developers/treasury/escrow/{hold_id}/release", payload or {}, idempotency_key=idempotency_key, token_type="dashboard")
+
+    def list_vendor_settlements(self):
+        return self.get("/developers/treasury/settlements", token_type="dashboard")
+
+    def execute_vendor_settlement(self, settlement_id, payload=None, idempotency_key=None):
+        return self.post(f"/developers/treasury/settlements/{settlement_id}/execute", payload or {}, idempotency_key=idempotency_key, token_type="dashboard")
+
+    def list_collections(self):
+        return self.get("/developers/collections", token_type="dashboard")
+
+    def create_collection(self, payload):
+        return self.post("/developers/collections", payload, token_type="dashboard")
+
+    def update_collection(self, collection_id, payload):
+        return self.patch(f"/developers/collections/{collection_id}", payload, token_type="dashboard")
+
+    def list_collection_payments(self, collection_id):
+        return self.get(f"/developers/collections/{collection_id}/payments", token_type="dashboard")
+
+    def public_collection(self, slug):
+        return self.get(f"/public/collections/{slug}", token_type="none")
+
+    def pay_collection(self, slug, payload):
+        return self.post(f"/public/collections/{slug}/pay", payload, token_type="none")
+
+    def update_settlement(self, payload):
+        return self.post("/developers/settlement", payload, token_type="dashboard")
+
+    def verify_settlement_account(self, payload):
+        return self.post("/developers/verify-account", payload, token_type="dashboard")
+
+    def kyc(self):
+        return self.get("/developers/kyc", token_type="dashboard")
+
+    def submit_kyc(self, payload):
+        return self.post("/developers/kyc", payload, token_type="dashboard")
+
+    def request_compliance_review(self, payload=None):
+        return self.post("/developers/compliance/request-review", payload or {}, token_type="dashboard")
+
+    @staticmethod
+    def parse_webhook(raw_body):
+        return json.loads(raw_body) if isinstance(raw_body, str) else raw_body

finswitz-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "finswitz"
+version = "1.0.0"
+description = "Official Python SDK for the Finswitz API"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Finswitz" }
+]
+requires-python = ">=3.8"
+keywords = [
+    "payments",
+    "fintech",
+    "finswitz",
+    "api"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+[tool.setuptools]
+py-modules = ["finswitz"]

finswitz-1.0.0/setup.cfg

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