sebpay 0.2.0__tar.gz

sebpay-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,115 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "sebpay"
+version = "0.2.0"
+description = "Official Python SDK for Sebpay hosted checkout — create a checkout session, redirect your customer, confirm the payment and verify webhooks."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sebpay" }]
+keywords = ["sebpay", "payment", "payments", "checkout", "mobile-money", "africa", "webhook", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.urls]
+Homepage = "https://sebpay.africa"
+Repository = "https://github.com/mjims/sebpay-sdk-py"
+Issues = "https://github.com/mjims/sebpay-sdk-py/issues"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sebpay*"]
+
+[tool.setuptools.package-data]
+sebpay = ["py.typed"]

sebpay-0.2.0/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-0.2.0/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-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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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/sebpay.egg-info/PKG-INFO

@@ -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/sebpay.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+sebpay/__init__.py
+sebpay/_version.py
+sebpay/client.py
+sebpay/errors.py
+sebpay/py.typed
+sebpay/types.py
+sebpay/webhooks.py
+sebpay.egg-info/PKG-INFO
+sebpay.egg-info/SOURCES.txt
+sebpay.egg-info/dependency_links.txt
+sebpay.egg-info/requires.txt
+sebpay.egg-info/top_level.txt
+sebpay/resources/__init__.py
+sebpay/resources/checkout_sessions.py
+tests/test_client.py
+tests/test_webhooks.py

sebpay-0.2.0/sebpay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sebpay-0.2.0/sebpay.egg-info/requires.txt

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

sebpay-0.2.0/sebpay.egg-info/top_level.txt

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

sebpay-0.2.0/setup.cfg

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

sebpay-0.2.0/tests/test_client.py

@@ -0,0 +1,166 @@
+import json
+import re
+import socket
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+import sebpay
+from sebpay import SebpayApiError, SebpayClient
+
+
+def _json(handler, status, payload):
+    raw = json.dumps(payload).encode()
+    handler.send_response(status)
+    handler.send_header("Content-Type", "application/json")
+    handler.send_header("Content-Length", str(len(raw)))
+    handler.end_headers()
+    handler.wfile.write(raw)
+
+
+def _text(handler, status, text):
+    raw = text.encode()
+    handler.send_response(status)
+    handler.send_header("Content-Type", "text/html")
+    handler.send_header("Content-Length", str(len(raw)))
+    handler.end_headers()
+    handler.wfile.write(raw)
+
+
+class FakeApi(BaseHTTPRequestHandler):
+    """A local stand-in for the API: the first path segment picks the answer."""
+
+    last = None
+
+    def log_message(self, *args):
+        pass
+
+    def _handle(self):
+        length = int(self.headers.get("Content-Length") or 0)
+        raw = self.rfile.read(length).decode() if length else ""
+        FakeApi.last = {"method": self.command, "path": self.path, "headers": dict(self.headers), "raw": raw}
+        mode = self.path.split("/")[1]
+        if mode == "ok":
+            _json(self, 200, {"success": True, "data": {"echo": {"method": self.command, "url": self.path, "body": json.loads(raw) if raw else None}}})
+        elif mode == "conflict":
+            _json(self, 409, {"success": False, "message": "Already used", "errors": {"code": "EXTERNAL_REFERENCE_CONFLICT"}})
+        elif mode == "invalid":
+            _json(self, 422, {"success": False, "message": "Validation Error.", "errors": {"redirect_url": ["required"]}})
+        elif mode == "refused":
+            _json(self, 200, {"success": False, "message": "Refused"})
+        elif mode == "nodata":
+            _json(self, 200, {"success": True})
+        elif mode == "html":
+            _text(self, 200, "<html>maintenance</html>")
+        elif mode == "gateway":
+            _text(self, 502, "<html>Bad gateway</html>")
+        elif mode == "slow":
+            time.sleep(1.5)
+            _json(self, 200, {"success": True, "data": {}})
+
+    do_GET = _handle
+    do_POST = _handle
+
+
+def _free_port():
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), FakeApi)
+        cls.server.daemon_threads = True
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.base = f"http://127.0.0.1:{cls.server.server_address[1]}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def client(self, mode, **options):
+        return SebpayClient("pk_test_pub", "sk_test_sec", base_url=f"{self.base}/{mode}", **options)
+
+    def test_base_url_follows_the_key_prefix(self):
+        self.assertEqual(SebpayClient("pk_test_x", "sk_test_x").base_url, "https://api.sandbox.sebpay.bj/api/v1")
+        self.assertEqual(SebpayClient("pk_live_x", "sk_live_x").base_url, "https://newapi.sebpay.africa/api/v1")
+        self.assertEqual(SebpayClient("pk_test_x", "sk_test_x", base_url="http://localhost:8000/api/v1/").base_url, "http://localhost:8000/api/v1")
+
+    def test_only_hosted_checkout_is_exposed(self):
+        client = self.client("ok")
+        self.assertTrue(callable(client.checkout_sessions.create) and callable(client.checkout_sessions.retrieve))
+        for gone in ("collections", "payouts", "references", "request"):
+            self.assertFalse(hasattr(client, gone), gone)
+        self.assertEqual(sorted(sebpay.__all__), ["SIGNATURE_HEADER", "SebpayApiError", "SebpayClient", "verify_signature"])
+
+    def test_version_matches_pyproject(self):
+        pyproject = (Path(__file__).resolve().parents[1] / "pyproject.toml").read_text(encoding="utf-8")
+        self.assertEqual(re.search(r'^version = "([^"]+)"', pyproject, re.M).group(1), sebpay.__version__)
+
+    def test_create_posts_json_with_the_keys_and_user_agent(self):
+        echo = self.client("ok").checkout_sessions.create(amount=5000, currency="XOF", redirect_url="https://shop.test/r", metadata={"a": 1})["echo"]
+        self.assertEqual(echo, {"method": "POST", "url": "/ok/checkout/sessions", "body": {"amount": 5000, "currency": "XOF", "redirect_url": "https://shop.test/r", "metadata": {"a": 1}}})
+        headers = FakeApi.last["headers"]
+        self.assertEqual(headers["X-Public-Key"], "pk_test_pub")
+        self.assertEqual(headers["X-Secret-Key"], "sk_test_sec")
+        self.assertEqual(headers["User-Agent"], f"sebpay-python/{sebpay.__version__}")
+        self.assertEqual(headers["Content-Type"], "application/json")
+        self.assertEqual(headers["Accept"], "application/json")
+
+    def test_retrieve_gets_the_encoded_id_without_body(self):
+        echo = self.client("ok").checkout_sessions.retrieve("A/B C?d")["echo"]
+        self.assertEqual(echo["url"], "/ok/checkout/sessions/A%2FB%20C%3Fd")
+        self.assertEqual(echo["method"], "GET")
+        self.assertEqual(FakeApi.last["raw"], "")
+
+    def test_api_error_carries_status_code_and_body(self):
+        with self.assertRaises(SebpayApiError) as ctx:
+            self.client("conflict").checkout_sessions.retrieve("x")
+        err = ctx.exception
+        self.assertEqual((err.status, err.code, str(err)), (409, "EXTERNAL_REFERENCE_CONFLICT", "Already used"))
+        self.assertEqual(err.body["errors"], {"code": "EXTERNAL_REFERENCE_CONFLICT"})
+
+    def test_error_without_code_has_code_none(self):
+        with self.assertRaises(SebpayApiError) as ctx:
+            self.client("invalid").checkout_sessions.retrieve("x")
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (422, None))
+        self.assertEqual(ctx.exception.body["errors"]["redirect_url"], ["required"])
+
+    def test_success_false_is_an_error_even_with_200(self):
+        with self.assertRaises(SebpayApiError) as ctx:
+            self.client("refused").checkout_sessions.retrieve("x")
+        self.assertEqual((ctx.exception.status, str(ctx.exception)), (200, "Refused"))
+
+    def test_2xx_without_data_or_not_json_is_invalid_response(self):
+        for mode in ("nodata", "html"):
+            with self.subTest(mode), self.assertRaises(SebpayApiError) as ctx:
+                self.client(mode).checkout_sessions.retrieve("x")
+            self.assertEqual((ctx.exception.status, ctx.exception.code), (200, "INVALID_RESPONSE"))
+
+    def test_non_json_error_page_keeps_status_and_text(self):
+        with self.assertRaises(SebpayApiError) as ctx:
+            self.client("gateway").checkout_sessions.retrieve("x")
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (502, None))
+        self.assertIn("Bad gateway", ctx.exception.body)
+
+    def test_no_server_is_network_error(self):
+        client = SebpayClient("pk_test_x", "sk_test_x", base_url=f"http://127.0.0.1:{_free_port()}")
+        with self.assertRaises(SebpayApiError) as ctx:
+            client.checkout_sessions.retrieve("x")
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (0, "NETWORK_ERROR"))
+
+    def test_timeout_aborts_a_slow_request(self):
+        started = time.monotonic()
+        with self.assertRaises(SebpayApiError) as ctx:
+            self.client("slow", timeout=0.2).checkout_sessions.retrieve("x")
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (0, "TIMEOUT"))
+        self.assertLess(time.monotonic() - started, 1.2)
+
+
+if __name__ == "__main__":
+    unittest.main()

sebpay-0.2.0/tests/test_webhooks.py

@@ -0,0 +1,28 @@
+import json
+import unittest
+from pathlib import Path
+
+from sebpay import SIGNATURE_HEADER, verify_signature
+
+VECTORS = json.loads((Path(__file__).resolve().parents[2] / "test-vectors" / "webhooks.json").read_text(encoding="utf-8"))
+
+
+class SignatureVectors(unittest.TestCase):
+    def test_vectors(self):
+        for case in VECTORS["cases"]:
+            for body in (case["body"].encode("utf-8"), case["body"]):
+                with self.subTest(case["name"], body_type=type(body).__name__):
+                    self.assertIs(verify_signature(body, case["signature"], VECTORS["secret_key"]), case["valid"])
+
+    def test_missing_or_odd_inputs_return_false_without_raising(self):
+        ok = VECTORS["cases"][0]
+        self.assertIs(verify_signature(ok["body"].encode(), None, VECTORS["secret_key"]), False)
+        self.assertIs(verify_signature(ok["body"].encode(), "é" * 64, VECTORS["secret_key"]), False)
+        self.assertIs(verify_signature(None, ok["signature"], VECTORS["secret_key"]), False)
+
+    def test_signature_header(self):
+        self.assertEqual(SIGNATURE_HEADER, "X-SebPay-Signature")
+
+
+if __name__ == "__main__":
+    unittest.main()