sebpay 0.2.0__py3-none-any.whl

sebpay/__init__.py

@@ -0,0 +1,6 @@
+from ._version import __version__
+from .client import SebpayClient
+from .errors import SebpayApiError
+from .webhooks import SIGNATURE_HEADER, verify_signature
+
+__all__ = ["SebpayClient", "SebpayApiError", "verify_signature", "SIGNATURE_HEADER"]

sebpay/_version.py

@@ -0,0 +1,2 @@
+# Sent in the User-Agent header. Keep in sync with pyproject.toml (checked by the tests).
+__version__ = "0.2.0"

sebpay/client.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+from ._version import __version__
+from .errors import SebpayApiError
+from .resources.checkout_sessions import CheckoutSessions
+
+LIVE_BASE_URL = "https://newapi.sebpay.africa/api/v1"
+SANDBOX_BASE_URL = "https://api.sandbox.sebpay.bj/api/v1"
+DEFAULT_TIMEOUT = 30
+
+
+class SebpayClient:
+    """Entry point for Sebpay hosted checkout. Pass the key pair from your
+    dashboard (API développeur): the sandbox and live are separate servers,
+    and pk_test_ keys are sent to the sandbox, pk_live_ keys to live.
+    `base_url` overrides that choice; `timeout` is in seconds.
+    """
+
+    def __init__(self, public_key: str, secret_key: str, base_url: Optional[str] = None, timeout: float = DEFAULT_TIMEOUT):
+        self._public_key = public_key
+        self._secret_key = secret_key
+        self._timeout = timeout
+        self.base_url = (base_url or (SANDBOX_BASE_URL if public_key.startswith("pk_test_") else LIVE_BASE_URL)).rstrip("/")
+        self._session = requests.Session()
+
+        # The transport stays private: the SDK only calls the endpoints it wraps
+        self.checkout_sessions = CheckoutSessions(self._request)
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        """Returns the `data` field of a successful response; raises SebpayApiError otherwise."""
+        headers = {
+            "X-Public-Key": self._public_key,
+            "X-Secret-Key": self._secret_key,
+            "Accept": "application/json",
+            "User-Agent": f"sebpay-python/{__version__}",
+        }
+
+        try:
+            response = self._session.request(method, f"{self.base_url}{path}", headers=headers, json=body, timeout=self._timeout)
+        except requests.Timeout as e:
+            raise SebpayApiError(f"Sebpay request timed out after {self._timeout} s", 0, None, code="TIMEOUT") from e
+        except requests.RequestException as e:
+            raise SebpayApiError(f"Sebpay request failed: {e}", 0, None, code="NETWORK_ERROR") from e
+
+        try:
+            decoded = response.json()
+        except ValueError:
+            decoded = None
+        error_body = decoded if decoded is not None else response.text
+
+        if not 200 <= response.status_code < 300 or (isinstance(decoded, dict) and decoded.get("success") is False):
+            errors = decoded.get("errors") if isinstance(decoded, dict) else None
+            code = errors.get("code") if isinstance(errors, dict) else None
+            message = decoded.get("message") if isinstance(decoded, dict) else None
+            raise SebpayApiError(
+                message if isinstance(message, str) else f"Sebpay API error (HTTP {response.status_code})",
+                response.status_code,
+                error_body,
+                code=code if isinstance(code, str) else None,
+            )
+
+        if not isinstance(decoded, dict) or not isinstance(decoded.get("data"), dict):
+            raise SebpayApiError("Sebpay API returned an unexpected response", response.status_code, error_body, code="INVALID_RESPONSE")
+
+        return decoded["data"]

sebpay/errors.py

@@ -0,0 +1,17 @@
+from typing import Any, Optional
+
+
+class SebpayApiError(Exception):
+    """Raised for every failed call.
+
+    status: the HTTP status, or 0 when no response came back (code "NETWORK_ERROR" or "TIMEOUT").
+    code: the API's errors.code when it sends one ("EXTERNAL_REFERENCE_CONFLICT", "RATE_LIMITED",
+          "WRONG_ENVIRONMENT"…), else None.
+    body: the decoded response (its text when it was not JSON).
+    """
+
+    def __init__(self, message: str, status: int, body: Any = None, code: Optional[str] = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.body = body

sebpay/resources/checkout_sessions.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+from urllib.parse import quote
+
+if TYPE_CHECKING:
+    from ..types import CheckoutSession, CheckoutSessionDetails
+
+
+class CheckoutSessions:
+    def __init__(self, request: Callable[..., Any]):
+        self._request = request
+
+    def create(self, **params: Any) -> CheckoutSession:
+        """Create a hosted checkout session. Returns `checkout_url` — redirect
+        your customer's browser there.
+
+        Params: amount, currency, redirect_url (required), external_reference,
+        callback_url, customer_name, customer_email, customer_phone, metadata (optional).
+        Sending an external_reference again with the same parameters returns the
+        same session with `idempotent_replay` = True.
+        """
+        return self._request("POST", "/checkout/sessions", params)
+
+    def retrieve(self, id_or_reference: str) -> CheckoutSessionDetails:
+        """Retrieve a session by its id (the `checkout_session_id` of your
+        redirect_url), its token or your external_reference. This is the
+        server-to-server confirmation: when your customer comes back, deliver
+        only if `transaction_status` is "approved" — the redirect alone proves nothing."""
+        return self._request("GET", f"/checkout/sessions/{quote(id_or_reference, safe='')}")

sebpay/types.py

@@ -0,0 +1,46 @@
+"""Shapes of what the API returns, for type checkers and editors — plain dicts at runtime."""
+
+from typing import Any, Dict, Literal, Optional, TypedDict
+
+CheckoutSessionStatus = Literal["open", "completed", "expired", "canceled"]
+
+
+class _CheckoutSessionFields(TypedDict):
+    id: str
+    status: CheckoutSessionStatus
+    checkout_url: str
+    amount: float
+    currency: str
+    external_reference: Optional[str]
+    metadata: Optional[Dict[str, Any]]
+    expires_at: str
+
+
+class CheckoutSession(_CheckoutSessionFields, total=False):
+    # present (True) when this external_reference had already created the session
+    idempotent_replay: bool
+
+
+class CheckoutSessionDetails(_CheckoutSessionFields):
+    transaction_id: Optional[str]
+    # "approved" is the only status that means paid
+    transaction_status: Optional[Literal["pending", "approved", "rejected"]]
+    created_at: str
+
+
+class _WebhookPayloadFields(TypedDict):
+    transaction_id: str
+    external_reference: Optional[str]
+    # only final statuses are sent
+    status: Literal["approved", "rejected"]
+    amount: float
+    currency: str
+    customer_phone: Optional[str]
+    created_at: str
+    updated_at: str
+
+
+class WebhookPayload(_WebhookPayloadFields, total=False):
+    # a hosted checkout's webhook names its session and echoes its metadata
+    checkout_session_id: str
+    metadata: Optional[Dict[str, Any]]

sebpay/webhooks.py

@@ -0,0 +1,22 @@
+import hashlib
+import hmac
+from typing import Optional, Union
+
+SIGNATURE_HEADER = "X-SebPay-Signature"
+
+
+def verify_signature(raw_body: Union[bytes, str], signature: Optional[str], secret_key: str) -> bool:
+    """Verify the `X-SebPay-Signature` header Sebpay sends with every webhook
+    callback. Always pass the raw request body — re-serializing a parsed
+    payload (e.g. via json.dumps after parsing) can reorder keys and break
+    the signature. A missing signature returns False.
+    """
+    if not isinstance(signature, str) or not signature:
+        return False
+    if isinstance(raw_body, str):
+        raw_body = raw_body.encode("utf-8")
+    if not isinstance(raw_body, (bytes, bytearray)):
+        return False
+
+    expected = hmac.new(secret_key.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected.encode("ascii"), signature.encode("utf-8"))

sebpay-0.2.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: sebpay
+Version: 0.2.0
+Summary: Official Python SDK for Sebpay hosted checkout — create a checkout session, redirect your customer, confirm the payment and verify webhooks.
+Author: Sebpay
+License-Expression: MIT
+Project-URL: Homepage, https://sebpay.africa
+Project-URL: Repository, https://github.com/mjims/sebpay-sdk-py
+Project-URL: Issues, https://github.com/mjims/sebpay-sdk-py/issues
+Keywords: sebpay,payment,payments,checkout,mobile-money,africa,webhook,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# sebpay-python
+
+Official Python SDK for [Sebpay](https://sebpay.africa) **hosted checkout**. It does four things:
+- create a checkout session;
+- redirect your customer to the Sebpay payment page;
+- confirm the payment when they come back;
+- verify Sebpay's webhooks.
+
+Its only dependency is `requests`. Direct collections, payouts and reference data are not part of the SDK. They remain available over the plain HTTP API.
+
+## Install
+
+```bash
+pip install sebpay
+```
+
+Requires Python 3.9 or later. The package ships its type hints (`py.typed`).
+
+## Usage
+
+### 1. Create a session and redirect your customer
+
+```python
+import os
+from sebpay import SebpayClient
+
+# Keys from your dashboard (API développeur): pk_test_ keys go to the sandbox server, pk_live_ keys to live.
+sebpay = SebpayClient(os.environ["SEBPAY_PUBLIC_KEY"], os.environ["SEBPAY_SECRET_KEY"])
+
+session = sebpay.checkout_sessions.create(
+    amount=5000,
+    currency="XOF",
+    redirect_url="https://yoursite.com/orders/return",
+    external_reference=order.id,  # your order id: sending it again returns the same session
+    callback_url="https://yoursite.com/webhook/sebpay",
+    metadata={"order_id": order.id},
+)
+
+return redirect(session["checkout_url"])
+```
+
+### 2. Confirm the payment when your customer comes back
+
+Your `redirect_url` receives `?checkout_session_id=<id>`. Coming back proves nothing, so ask Sebpay before you deliver:
+
+```python
+session = sebpay.checkout_sessions.retrieve(request.args["checkout_session_id"])
+
+if session["transaction_status"] == "approved":
+    ...  # Paid: deliver the order (session["external_reference"], session["metadata"]).
+```
+
+`retrieve()` also accepts your `external_reference`.
+
+### 3. Verify the webhook
+
+Sebpay POSTs the final status (`approved` or `rejected`) to your `callback_url`. For a checkout, the request also carries `checkout_session_id` and your `metadata`.
+
+```python
+from sebpay import SIGNATURE_HEADER, verify_signature
+
+# With Flask:
+if not verify_signature(request.get_data(), request.headers.get(SIGNATURE_HEADER), os.environ["SEBPAY_SECRET_KEY"]):
+    return {"error": "Invalid signature"}, 401
+
+payload = request.get_json()  # payload["status"]: "approved" | "rejected"
+```
+
+- Always pass the **raw** request body. Re-serializing a parsed payload can reorder keys and break the signature.
+- A missing header returns `False`.
+
+The shapes of the session and of the webhook payload are described as `TypedDict`s in `sebpay.types`, for editors and type checkers.
+
+## Options
+
+```python
+SebpayClient(public_key, secret_key,
+             base_url="http://localhost:8000/api/v1",  # only to test against a local API; otherwise chosen from the keys
+             timeout=10)                               # seconds, default 30
+```
+
+`sebpay.base_url` tells which server the client talks to.
+
+## Errors
+
+Every failed call raises a `SebpayApiError`, with three attributes:
+- `status`: the HTTP status, or 0 when no response came back;
+- `code`: the API's `errors.code`, or one of the SDK's own codes. Examples: `EXTERNAL_REFERENCE_CONFLICT`, `RATE_LIMITED`, `WRONG_ENVIRONMENT`, `NETWORK_ERROR`, `TIMEOUT`, `INVALID_RESPONSE`. It is `None` otherwise;
+- `body`: the decoded response.
+
+```python
+from sebpay import SebpayApiError
+
+try:
+    sebpay.checkout_sessions.create(...)
+except SebpayApiError as e:
+    if e.code == "EXTERNAL_REFERENCE_CONFLICT":
+        ...  # This order id was already used with other parameters.
+```
+
+## Examples
+
+See [`examples/`](https://github.com/mjims/sebpay-sdk-py/tree/main/examples). Set `SEBPAY_PUBLIC_KEY` and `SEBPAY_SECRET_KEY`, then:
+- `python examples/create_checkout.py` creates a session and prints its `checkout_url`;
+- `python examples/webhook_server.py` starts a Flask server (`pip install flask`) that handles the webhook and the return page, on `PORT` (default 3002).
+
+For local testing, also set `SEBPAY_BASE_URL`.
+
+## Tests
+
+`python -m unittest discover -s tests` runs the SDK's offline tests. They cover the transport, against a local HTTP server, and the shared signature vectors.
+
+## Requirements
+
+Python 3.9+ and `requests`.

sebpay-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sebpay/__init__.py,sha256=UuigNpLJwqXRMhdBn0RrNi-EOvntvdIz-uqsvroIMwI,245
+sebpay/_version.py,sha256=5ZigdfGhEeFjFeCFr4RORO5cwspqJiL1TNKf_jUYSmI,112
+sebpay/client.py,sha256=_0AAJB75Q-Gk74ZKh32jxMPxAx8ht1Ma4iqFQFLXoVY,3144
+sebpay/errors.py,sha256=Im5_LSIqXLoe81Sxli4FKV5E8oyESxIP_JyHSGPI9ZA,631
+sebpay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sebpay/types.py,sha256=SlDrabcg7LBHJfxn7J_sveyMl-UatebY_UWX3NTiAhY,1385
+sebpay/webhooks.py,sha256=0--Jxl6SO-S60dwFx3Jf8cygbvbqN-iZq5VP65GO4kY,901
+sebpay/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sebpay/resources/checkout_sessions.py,sha256=r27Tk9dpbyK3v_XtTsHNKyUZy-TFY79fXiVq7s2Haw4,1355
+sebpay-0.2.0.dist-info/licenses/LICENSE,sha256=G0ZKDwtA6iyZ4FSBTtv7aTtF5_gqfi0pNl2iMRufKTg,1063
+sebpay-0.2.0.dist-info/METADATA,sha256=DrnyCzeuAHngOIZbXvPj98FtMoq3JUbDoCrENh4J4FY,5303
+sebpay-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sebpay-0.2.0.dist-info/top_level.txt,sha256=XP-Kn6okZAJvxZZYrd_TWeq8CCzelx3_8C_covvf4Zk,7
+sebpay-0.2.0.dist-info/RECORD,,

sebpay-0.2.0.dist-info/WHEEL

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

sebpay-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebpay
+
+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.

sebpay-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sebpay