kobara 2.0.0__tar.gz

kobara-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kobara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kobara-2.0.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: kobara
+Version: 2.0.0
+Summary: Official Python SDK for Kobara payments and MonCash/NatCash withdrawals
+Author-email: Kobara Dev Team <dev@kobara.app>
+License-Expression: MIT
+Project-URL: Documentation, https://docs.kobara.app/docs/python-sdk
+Project-URL: Homepage, https://kobara.app
+Project-URL: Repository, https://github.com/L09DP01/Kobara-python
+Project-URL: Issues, https://github.com/L09DP01/Kobara-python/issues
+Keywords: kobara,moncash,haiti,payments,fintech,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# Kobara Python SDK
+
+SDK serveur officiel pour les paiements Kobara, les retraits MonCash/NatCash et la vérification des webhooks.
+
+```bash
+pip install kobara
+```
+
+```python
+from kobara import Kobara
+
+client = Kobara(api_key="kbr_sk_live_...")
+payment = client.payments.create({
+    "amount": 2500,
+    "currency": "HTG",
+    "provider": "kobara",
+    "success_url": "https://shop.example/success",
+    "cancel_url": "https://shop.example/cancel",
+}, idempotency_key="payment-1001")
+
+print(payment["data"]["checkout_url"])
+```
+
+Les fournisseurs acceptés sont `kobara`, MonCash, NatCash, carte, PayPal, Apple Pay et Google Pay, avec leurs identifiants détaillés dans la documentation. Leur disponibilité dépend des activations du marchand et du système.
+
+```python
+withdrawal = client.withdrawals.create({
+    "amount": 1000,
+    "method": "natcash",
+    "account_currency": "HTG",
+    "wallet": "50941234567",
+}, idempotency_key="withdrawal-1001")
+```
+
+Les retraits API acceptent uniquement `moncash` et `natcash`. L'URL par défaut est `https://api.kobara.app/v1`; une UUID d'idempotence est générée si elle est omise.
+
+Documentation: https://docs.kobara.app/docs/python-sdk

kobara-2.0.0/README.md

@@ -0,0 +1,37 @@
+# Kobara Python SDK
+
+SDK serveur officiel pour les paiements Kobara, les retraits MonCash/NatCash et la vérification des webhooks.
+
+```bash
+pip install kobara
+```
+
+```python
+from kobara import Kobara
+
+client = Kobara(api_key="kbr_sk_live_...")
+payment = client.payments.create({
+    "amount": 2500,
+    "currency": "HTG",
+    "provider": "kobara",
+    "success_url": "https://shop.example/success",
+    "cancel_url": "https://shop.example/cancel",
+}, idempotency_key="payment-1001")
+
+print(payment["data"]["checkout_url"])
+```
+
+Les fournisseurs acceptés sont `kobara`, MonCash, NatCash, carte, PayPal, Apple Pay et Google Pay, avec leurs identifiants détaillés dans la documentation. Leur disponibilité dépend des activations du marchand et du système.
+
+```python
+withdrawal = client.withdrawals.create({
+    "amount": 1000,
+    "method": "natcash",
+    "account_currency": "HTG",
+    "wallet": "50941234567",
+}, idempotency_key="withdrawal-1001")
+```
+
+Les retraits API acceptent uniquement `moncash` et `natcash`. L'URL par défaut est `https://api.kobara.app/v1`; une UUID d'idempotence est générée si elle est omise.
+
+Documentation: https://docs.kobara.app/docs/python-sdk

kobara-2.0.0/kobara/__init__.py

@@ -0,0 +1,13 @@
+from kobara.client import KobaraClient, Kobara
+from kobara.errors import KobaraError, KobaraAPIError, KobaraSignatureVerificationError
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "KobaraClient",
+    "Kobara",
+    "KobaraError",
+    "KobaraAPIError",
+    "KobaraSignatureVerificationError",
+    "__version__",
+]

kobara-2.0.0/kobara/client.py

@@ -0,0 +1,57 @@
+import requests
+from typing import Optional, Dict, Any
+from kobara.errors import KobaraAPIError
+from kobara.resources.payments import PaymentsResource
+from kobara.resources.withdrawals import WithdrawalsResource
+from kobara.resources.webhooks import WebhooksResource
+
+class KobaraClient:
+    def __init__(self, api_key: str, base_url: Optional[str] = None):
+        if not api_key:
+            raise ValueError("API Key (api_key) is required to initialize KobaraClient")
+
+        self.api_key = api_key
+        self.base_url = (base_url or "https://api.kobara.app/v1").rstrip("/")
+
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "Kobara-Python/2.0.0",
+        })
+
+        # Register Resources
+        self.payments = PaymentsResource(self)
+        self.withdrawals = WithdrawalsResource(self)
+        self.webhooks = WebhooksResource()
+
+    def request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
+        """
+        Internal request dispatcher with error formatting and exception raised.
+        """
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+
+        kwargs.setdefault("timeout", 30)
+
+        try:
+            response = self.session.request(method, url, **kwargs)
+        except requests.RequestException as e:
+            raise RuntimeError(f"Failed to connect to Kobara API: {str(e)}")
+
+        try:
+            data = response.json()
+        except ValueError:
+            data = {}
+
+        if not (200 <= response.status_code < 300):
+            message = data.get("message") or data.get("error") or response.reason or "Unknown API Error"
+            if not isinstance(message, str):
+                message = str(message)
+            error_type = data.get("type", "api_error")
+            raise KobaraAPIError(message, status_code=response.status_code, error_type=error_type)
+
+        return data
+
+# Export alias to match traditional class names
+Kobara = KobaraClient

kobara-2.0.0/kobara/errors.py

@@ -0,0 +1,14 @@
+class KobaraError(Exception):
+    """Base exception for all Kobara errors."""
+    pass
+
+class KobaraAPIError(KobaraError):
+    """Exception raised when an API request returns an error response."""
+    def __init__(self, message, status_code=None, error_type=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_type = error_type
+
+class KobaraSignatureVerificationError(KobaraError):
+    """Exception raised when webhook signature verification fails."""
+    pass

kobara-2.0.0/kobara/py.typed

@@ -0,0 +1 @@
+

kobara-2.0.0/kobara/resources/payments.py

@@ -0,0 +1,15 @@
+from typing import Dict, Any, Optional
+from uuid import uuid4
+
+class PaymentsResource:
+    def __init__(self, client):
+        self.client = client
+
+    def create(self, payload: Dict[str, Any], idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Create a payment using the unified checkout or a supported provider.
+        """
+        headers = {}
+        headers["Idempotency-Key"] = idempotency_key or str(uuid4())
+
+        return self.client.request("POST", "/payments", json=payload, headers=headers)

kobara-2.0.0/kobara/resources/webhooks.py

@@ -0,0 +1,46 @@
+import hmac
+import hashlib
+import json
+import re
+import time
+from kobara.errors import KobaraSignatureVerificationError
+
+class WebhooksResource:
+    @staticmethod
+    def construct_event(payload: str, signature: str, secret: str, tolerance_seconds: int = 300) -> dict:
+        """
+        Securely verify webhook payload signature locally using HMAC SHA-256
+        """
+        if not payload:
+            raise KobaraSignatureVerificationError("Payload cannot be empty")
+        if not signature:
+            raise KobaraSignatureVerificationError("Kobara-Signature header is missing")
+        if not secret:
+            raise KobaraSignatureVerificationError("Webhook secret is missing")
+
+        parts = dict(part.strip().split("=", 1) for part in signature.split(",") if "=" in part)
+        try:
+            timestamp = int(parts["t"])
+            target_signature = parts["v1"]
+        except (KeyError, ValueError):
+            raise KobaraSignatureVerificationError("Invalid Kobara-Signature format")
+        if not re.fullmatch(r"[a-fA-F0-9]{64}", target_signature):
+            raise KobaraSignatureVerificationError("Invalid Kobara-Signature format")
+        if abs(int(time.time()) - timestamp) > tolerance_seconds:
+            raise KobaraSignatureVerificationError("Webhook timestamp is outside the tolerance window")
+
+        # Compute signature
+        computed = hmac.new(
+            secret.encode("utf-8"),
+            f"{timestamp}.{payload}".encode("utf-8"),
+            hashlib.sha256
+        ).hexdigest()
+
+        # Timing safe comparison
+        if not hmac.compare_digest(computed.lower(), target_signature.lower()):
+            raise KobaraSignatureVerificationError("Invalid signature. HMAC verification failed.")
+
+        try:
+            return json.loads(payload)
+        except Exception as e:
+            raise KobaraSignatureVerificationError(f"Failed to parse raw body payload as JSON: {str(e)}")

kobara-2.0.0/kobara/resources/withdrawals.py

@@ -0,0 +1,15 @@
+from typing import Dict, Any, Optional
+from uuid import uuid4
+
+class WithdrawalsResource:
+    def __init__(self, client):
+        self.client = client
+
+    def create(self, payload: Dict[str, Any], idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Request a MonCash or NatCash withdrawal.
+        """
+        headers = {}
+        headers["Idempotency-Key"] = idempotency_key or str(uuid4())
+
+        return self.client.request("POST", "/withdrawals", json=payload, headers=headers)

kobara-2.0.0/kobara/types.py

@@ -0,0 +1,68 @@
+from typing import TypedDict, Optional, Literal, Dict, Any
+
+class CustomerDict(TypedDict, total=False):
+    name: str
+    email: str
+    phone: str
+
+class PaymentCreateRequired(TypedDict):
+    amount: float
+
+class PaymentCreatePayload(PaymentCreateRequired, total=False):
+    currency: str
+    provider: Literal["kobara", "moncash", "moncash_web", "moncash_ussd", "natcash", "natcash_web", "natcash_ussd", "card", "carte", "paypal", "apple_pay", "google_pay"]
+    description: str
+    customer: CustomerDict
+    success_url: str
+    cancel_url: str
+    metadata: Dict[str, Any]
+
+class PaymentData(TypedDict):
+    id: str
+    reference: str
+    amount: float
+    net_amount: float
+    fee_amount: float
+    status: Literal["pending", "succeeded", "failed", "expired", "refunded"]
+    environment: Literal["test", "live"]
+    paid_at: Optional[str]
+    checkout_url: str
+    url: str
+    payment_url: str
+    paymentUrl: str
+
+class PaymentCreateResponse(TypedDict):
+    status: Literal["success"]
+    data: PaymentData
+
+class WithdrawalCreateRequired(TypedDict):
+    amount: float
+    wallet: str
+
+class WithdrawalCreatePayload(WithdrawalCreateRequired, total=False):
+    method: Literal["moncash", "natcash"]
+    account_currency: Literal["HTG", "USD"]
+    description: str
+
+class WithdrawalData(TypedDict):
+    id: str
+    reference: str
+    status: Literal["pending", "pending_approval", "completed"]
+    method: Literal["moncash", "natcash"]
+    amount: float
+    fees: float
+    net_amount: float
+    currency: Literal["HTG", "USD"]
+    payout_amount: float
+    payout_currency: Literal["HTG"]
+    exchange_rate: float
+    wallet: str
+    description: Optional[str]
+    created_at: str
+
+class WithdrawalResponseRequired(TypedDict):
+    status: Literal["success"]
+    data: WithdrawalData
+
+class WithdrawalResponse(WithdrawalResponseRequired, total=False):
+    verification_pending: bool

kobara-2.0.0/kobara.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: kobara
+Version: 2.0.0
+Summary: Official Python SDK for Kobara payments and MonCash/NatCash withdrawals
+Author-email: Kobara Dev Team <dev@kobara.app>
+License-Expression: MIT
+Project-URL: Documentation, https://docs.kobara.app/docs/python-sdk
+Project-URL: Homepage, https://kobara.app
+Project-URL: Repository, https://github.com/L09DP01/Kobara-python
+Project-URL: Issues, https://github.com/L09DP01/Kobara-python/issues
+Keywords: kobara,moncash,haiti,payments,fintech,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# Kobara Python SDK
+
+SDK serveur officiel pour les paiements Kobara, les retraits MonCash/NatCash et la vérification des webhooks.
+
+```bash
+pip install kobara
+```
+
+```python
+from kobara import Kobara
+
+client = Kobara(api_key="kbr_sk_live_...")
+payment = client.payments.create({
+    "amount": 2500,
+    "currency": "HTG",
+    "provider": "kobara",
+    "success_url": "https://shop.example/success",
+    "cancel_url": "https://shop.example/cancel",
+}, idempotency_key="payment-1001")
+
+print(payment["data"]["checkout_url"])
+```
+
+Les fournisseurs acceptés sont `kobara`, MonCash, NatCash, carte, PayPal, Apple Pay et Google Pay, avec leurs identifiants détaillés dans la documentation. Leur disponibilité dépend des activations du marchand et du système.
+
+```python
+withdrawal = client.withdrawals.create({
+    "amount": 1000,
+    "method": "natcash",
+    "account_currency": "HTG",
+    "wallet": "50941234567",
+}, idempotency_key="withdrawal-1001")
+```
+
+Les retraits API acceptent uniquement `moncash` et `natcash`. L'URL par défaut est `https://api.kobara.app/v1`; une UUID d'idempotence est générée si elle est omise.
+
+Documentation: https://docs.kobara.app/docs/python-sdk

kobara-2.0.0/kobara.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+kobara/__init__.py
+kobara/client.py
+kobara/errors.py
+kobara/py.typed
+kobara/types.py
+kobara.egg-info/PKG-INFO
+kobara.egg-info/SOURCES.txt
+kobara.egg-info/dependency_links.txt
+kobara.egg-info/requires.txt
+kobara.egg-info/top_level.txt
+kobara/resources/payments.py
+kobara/resources/webhooks.py
+kobara/resources/withdrawals.py
+tests/test_sdk.py

kobara-2.0.0/kobara.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kobara-2.0.0/kobara.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25.0

kobara-2.0.0/kobara.egg-info/top_level.txt

@@ -0,0 +1 @@
+kobara

kobara-2.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kobara"
+version = "2.0.0"
+description = "Official Python SDK for Kobara payments and MonCash/NatCash withdrawals"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+    {name = "Kobara Dev Team", email = "dev@kobara.app"}
+]
+keywords = ["kobara", "moncash", "haiti", "payments", "fintech", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+    "requests>=2.25.0"
+]
+
+[project.urls]
+Documentation = "https://docs.kobara.app/docs/python-sdk"
+Homepage = "https://kobara.app"
+Repository = "https://github.com/L09DP01/Kobara-python"
+Issues = "https://github.com/L09DP01/Kobara-python/issues"
+
+[tool.setuptools.packages.find]
+include = ["kobara*"]
+
+[tool.setuptools.package-data]
+kobara = ["py.typed"]

kobara-2.0.0/setup.cfg

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

kobara-2.0.0/tests/test_sdk.py

@@ -0,0 +1,65 @@
+import hashlib
+import hmac
+import json
+import time
+import unittest
+from unittest.mock import Mock
+
+from kobara import Kobara, KobaraSignatureVerificationError, __version__
+
+
+class KobaraSdkV2Tests(unittest.TestCase):
+    def setUp(self):
+        self.client = Kobara("kbr_sk_live_example")
+        self.client.session.request = Mock()
+        self.client.session.request.return_value.status_code = 200
+        self.client.session.request.return_value.json.return_value = {
+            "status": "success",
+            "data": {"id": "example"},
+        }
+
+    def test_version_and_default_base_url(self):
+        self.assertEqual(__version__, "2.0.0")
+        self.assertEqual(self.client.base_url, "https://api.kobara.app/v1")
+
+    def test_payment_uses_v1_route_and_idempotency(self):
+        self.client.payments.create({"amount": 2500, "provider": "kobara"})
+        _, url = self.client.session.request.call_args.args
+        kwargs = self.client.session.request.call_args.kwargs
+        self.assertEqual(url, "https://api.kobara.app/v1/payments")
+        self.assertIn("Idempotency-Key", kwargs["headers"])
+        self.assertEqual(kwargs["timeout"], 30)
+
+    def test_withdrawal_uses_v1_route(self):
+        self.client.withdrawals.create({
+            "amount": 1000,
+            "method": "moncash",
+            "account_currency": "HTG",
+            "wallet": "50934567890",
+        })
+        _, url = self.client.session.request.call_args.args
+        self.assertEqual(url, "https://api.kobara.app/v1/withdrawals")
+
+    def test_timestamped_webhook_signature(self):
+        payload = json.dumps({"event_type": "payment.succeeded", "data": {"id": "pay_1"}})
+        secret = "whsec_example"
+        timestamp = int(time.time())
+        digest = hmac.new(
+            secret.encode("utf-8"),
+            f"{timestamp}.{payload}".encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+        event = self.client.webhooks.construct_event(
+            payload,
+            f"t={timestamp},v1={digest}",
+            secret,
+        )
+        self.assertEqual(event["event_type"], "payment.succeeded")
+
+        with self.assertRaises(KobaraSignatureVerificationError):
+            self.client.webhooks.construct_event(payload, f"t={timestamp},v1={'0' * 64}", secret)
+
+
+if __name__ == "__main__":
+    unittest.main()