dominaite 0.1.0__tar.gz

dominaite-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run the test suite first
+        run: |
+          python -m pip install pytest
+          python -m pytest -q
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Publish (trusted publishing, no tokens)
+        uses: pypa/gh-action-pypi-publish@release/v1

dominaite-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+build/
+dist/

dominaite-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: dominaite
+Version: 0.1.0
+Summary: Server-side Python client for the Dominaite merchant API: create hosted checkout sessions from your own backend.
+License: Proprietary
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dominaite-python
+
+Server-side Python client for the Dominaite merchant API. One call from your backend opens a
+hosted checkout session; a two-line script tag renders the payment widget on your page. Card
+details go straight from your customer's browser into the payment widget - they never touch
+your server, which keeps your PCI scope minimal (SAQ A).
+
+Python 3.9+, standard library only. No `requests`, no framework, nothing to vendor.
+
+## Install
+
+The package name is `dominaite` on PyPI (verified free 2026-08-17; matches `import dominaite`,
+the same pattern Stripe uses). It is **not published yet** - until it is, install from a checkout:
+
+```bash
+pip install /path/to/dominaite-python-sdk
+# or, while you are working on the SDK itself:
+pip install -e /path/to/dominaite-python-sdk
+```
+
+## Credentials
+
+You get two values from the Dominaite dashboard, under **Online payments -> Website
+integration**, when you create an API key. The secret is shown **once** - store both like
+passwords:
+
+- `dmk_...` - your API key id. Identifies you; not secret by itself.
+- `dms_...` - your API secret. Server-side only: environment variable or a config file outside
+  the web root. Never in a browser, never in git, never in logs.
+
+Every request is signed with the secret (HMAC-SHA256) and timestamped. Keep your server clock
+on NTP - signatures older than 5 minutes are rejected.
+
+## Quickstart against dev
+
+Everything you need to go from nothing to a live session on the dev environment.
+
+**1. Set your credentials.** Both come from the dashboard's Website-integration tab (dev
+dashboard, dev key - a prod key will not authenticate against dev):
+
+```bash
+export DOMINAITE_KEY_ID='dmk_...'          # the key id shown on the tab
+export DOMINAITE_SECRET='dms_...'          # the secret shown once at key creation
+export DOMINAITE_BASE_URL='https://func-dom-gw-payments-dev-gwc-01.azurewebsites.net/api'
+```
+
+That base URL is the dev payments service. Production is
+`https://api.dominaite.com/payments`, which is the SDK's default when you pass no `base_url`.
+
+**2. Check your signing before you call anything.** This runs offline against the published
+test vector and authenticates nothing, so it can never fail for credential reasons:
+
+```bash
+python -m pytest tests/test_signing.py
+```
+
+**3. Mint a session** (`mint.py`):
+
+```python
+import os
+
+from dominaite import CheckoutRefusedError, DominaiteClient, TransportError
+
+client = DominaiteClient(
+    os.environ["DOMINAITE_KEY_ID"],
+    os.environ["DOMINAITE_SECRET"],
+    base_url=os.environ.get("DOMINAITE_BASE_URL", "https://api.dominaite.com/payments"),
+)
+
+try:
+    session = client.create_checkout_session(
+        amount=2500,                    # minor units: 2500 = 25.00 EUR
+        currency="EUR",
+        order_reference="order-1042",   # your own order id, shows up in your dashboard
+        customer={
+            # Pass everything you already know - prefilled fields are hidden from the
+            # payer, so the checkout form stays short.
+            "firstName": "Ana",
+            "lastName": "Kirova",
+            "email": "ana@example.com",
+        },
+        language="bg",                  # widget UI language
+        theme="dark",
+    )
+except CheckoutRefusedError as refusal:
+    # Machine-readable: refusal.error_code - see the exception docstring for the codes.
+    raise SystemExit("Payment unavailable: " + refusal.error_code)
+except TransportError:
+    # Network blip - safe to retry with the same idempotency_key.
+    raise SystemExit("Payment temporarily unavailable")
+
+print(session["transactionId"], session["cashierKey"], session["cashierToken"])
+```
+
+```bash
+python mint.py
+```
+
+A transaction id, cashier key and cashier token on stdout means the whole chain works: your
+credentials, your clock, your signing, and the dev gateway.
+
+**If it fails**, the error tells you which one:
+
+| What you see | What is wrong |
+|---|---|
+| `AuthenticationError` + `INVALID_API_KEY` | Wrong or revoked key id, or a prod key against dev. |
+| `AuthenticationError` + `INVALID_SIGNATURE` | Secret does not match the key id. |
+| `AuthenticationError` + `TIMESTAMP_OUT_OF_RANGE` | Your machine's clock is more than 5 minutes off. |
+| `AuthenticationError` + `IP_NOT_ALLOWED` | The key has an IP allowlist that does not include you. |
+| `CheckoutRefusedError` | You authenticated fine; the gateway declined to open a session. |
+| `TransportError` | Wrong base URL, or the service is down. Retry with the same key. |
+
+**4. Render the widget.** Store `session["transactionId"]` against your order, then hand the
+two cashier values to the page:
+
+```html
+<div id="checkout"></div>
+<script src="https://bp-checkout.dominaite.com/v2/launcher"
+        data-cashier-key="{{ cashier_key }}"
+        data-cashier-token="{{ cashier_token }}"></script>
+```
+
+HTML-escape both when templating (Jinja's autoescape does it for you). They are per-payment
+session values, not your credentials.
+
+That's the whole integration: the session call, the script tag, and your domain bound to your
+checkout by Dominaite during onboarding.
+
+## Amounts are minor units
+
+`amount` is always an integer in the currency's minor unit: `2500` is 25.00 EUR. A float or a
+string raises `ValueError` before anything is sent. The amount is locked server-side - what you
+pass here is what gets charged; nothing in the browser can change it.
+
+## Retries and double-charges
+
+Every `create_checkout_session` call carries an idempotency key (auto-generated, or pass your
+own as `idempotency_key`). Retrying with the same key never opens a second payment - on a
+timeout, retry with the same key rather than generating a new one.
+
+There is a helper that does exactly that:
+
+```python
+session = client.create_checkout_session_with_retry(
+    amount=2500,
+    currency="EUR",
+    order_reference="order-1042",
+    max_attempts=3,
+)
+```
+
+It retries only `TransportError` (network failures, 5xx, `MERCHANT_API_UNAVAILABLE`), reuses the
+one key across all attempts, and backs off between them. Refusals and authentication failures
+are raised immediately.
+
+## Sessions expire
+
+A session is valid for 2 hours. If the payer comes back later, create a new session.
+
+## Status polling
+
+```python
+status = client.get_status(session["transactionId"])
+# {"transactionId": ..., "orderReference": "order-1042", "status": "succeeded",
+#  "amount": 2500, "currency": "EUR", ...}
+```
+
+`status` is one of: `pending`, `processing`, `succeeded`, `failed`, `refunded`,
+`partially_refunded`, `cancelled`, `disputed`, `abandoned`. While the session is still payable
+the response also carries `expiresAt`; after that instant a `pending` session can only become
+`abandoned`. An unknown transaction id raises `ApiError` with `http_status == 404`.
+
+Poll after the payer returns to you, or on your order timeout - not in a tight loop; the
+endpoint is rate limited per key.
+
+## Errors
+
+| Exception | Means | Retry? |
+|---|---|---|
+| `AuthenticationError` | Bad credentials, bad signature, clock skew, IP not allowlisted | No - fix config |
+| `CheckoutRefusedError` | The gateway refused to open the session (`error_code`) | Depends on the code |
+| `ApiError` | Unexpected response, or a 4xx like an unknown transaction id (`http_status`) | No |
+| `TransportError` | Network failure or 5xx; you don't know if it landed | Yes, same idempotency key |
+
+All four inherit from `DominaiteError` if you only care that the call failed.
+
+## Running the tests
+
+```bash
+python -m venv .venv && .venv/bin/pip install pytest
+.venv/bin/python -m pytest
+```
+
+`tests/test_signing.py` reproduces the signing test vector published on the dashboard's
+Website-integration tab. If it ever fails, the SDK cannot authenticate - fix the signing, never
+the expected value.

dominaite-0.1.0/README.md

@@ -0,0 +1,196 @@
+# dominaite-python
+
+Server-side Python client for the Dominaite merchant API. One call from your backend opens a
+hosted checkout session; a two-line script tag renders the payment widget on your page. Card
+details go straight from your customer's browser into the payment widget - they never touch
+your server, which keeps your PCI scope minimal (SAQ A).
+
+Python 3.9+, standard library only. No `requests`, no framework, nothing to vendor.
+
+## Install
+
+The package name is `dominaite` on PyPI (verified free 2026-08-17; matches `import dominaite`,
+the same pattern Stripe uses). It is **not published yet** - until it is, install from a checkout:
+
+```bash
+pip install /path/to/dominaite-python-sdk
+# or, while you are working on the SDK itself:
+pip install -e /path/to/dominaite-python-sdk
+```
+
+## Credentials
+
+You get two values from the Dominaite dashboard, under **Online payments -> Website
+integration**, when you create an API key. The secret is shown **once** - store both like
+passwords:
+
+- `dmk_...` - your API key id. Identifies you; not secret by itself.
+- `dms_...` - your API secret. Server-side only: environment variable or a config file outside
+  the web root. Never in a browser, never in git, never in logs.
+
+Every request is signed with the secret (HMAC-SHA256) and timestamped. Keep your server clock
+on NTP - signatures older than 5 minutes are rejected.
+
+## Quickstart against dev
+
+Everything you need to go from nothing to a live session on the dev environment.
+
+**1. Set your credentials.** Both come from the dashboard's Website-integration tab (dev
+dashboard, dev key - a prod key will not authenticate against dev):
+
+```bash
+export DOMINAITE_KEY_ID='dmk_...'          # the key id shown on the tab
+export DOMINAITE_SECRET='dms_...'          # the secret shown once at key creation
+export DOMINAITE_BASE_URL='https://func-dom-gw-payments-dev-gwc-01.azurewebsites.net/api'
+```
+
+That base URL is the dev payments service. Production is
+`https://api.dominaite.com/payments`, which is the SDK's default when you pass no `base_url`.
+
+**2. Check your signing before you call anything.** This runs offline against the published
+test vector and authenticates nothing, so it can never fail for credential reasons:
+
+```bash
+python -m pytest tests/test_signing.py
+```
+
+**3. Mint a session** (`mint.py`):
+
+```python
+import os
+
+from dominaite import CheckoutRefusedError, DominaiteClient, TransportError
+
+client = DominaiteClient(
+    os.environ["DOMINAITE_KEY_ID"],
+    os.environ["DOMINAITE_SECRET"],
+    base_url=os.environ.get("DOMINAITE_BASE_URL", "https://api.dominaite.com/payments"),
+)
+
+try:
+    session = client.create_checkout_session(
+        amount=2500,                    # minor units: 2500 = 25.00 EUR
+        currency="EUR",
+        order_reference="order-1042",   # your own order id, shows up in your dashboard
+        customer={
+            # Pass everything you already know - prefilled fields are hidden from the
+            # payer, so the checkout form stays short.
+            "firstName": "Ana",
+            "lastName": "Kirova",
+            "email": "ana@example.com",
+        },
+        language="bg",                  # widget UI language
+        theme="dark",
+    )
+except CheckoutRefusedError as refusal:
+    # Machine-readable: refusal.error_code - see the exception docstring for the codes.
+    raise SystemExit("Payment unavailable: " + refusal.error_code)
+except TransportError:
+    # Network blip - safe to retry with the same idempotency_key.
+    raise SystemExit("Payment temporarily unavailable")
+
+print(session["transactionId"], session["cashierKey"], session["cashierToken"])
+```
+
+```bash
+python mint.py
+```
+
+A transaction id, cashier key and cashier token on stdout means the whole chain works: your
+credentials, your clock, your signing, and the dev gateway.
+
+**If it fails**, the error tells you which one:
+
+| What you see | What is wrong |
+|---|---|
+| `AuthenticationError` + `INVALID_API_KEY` | Wrong or revoked key id, or a prod key against dev. |
+| `AuthenticationError` + `INVALID_SIGNATURE` | Secret does not match the key id. |
+| `AuthenticationError` + `TIMESTAMP_OUT_OF_RANGE` | Your machine's clock is more than 5 minutes off. |
+| `AuthenticationError` + `IP_NOT_ALLOWED` | The key has an IP allowlist that does not include you. |
+| `CheckoutRefusedError` | You authenticated fine; the gateway declined to open a session. |
+| `TransportError` | Wrong base URL, or the service is down. Retry with the same key. |
+
+**4. Render the widget.** Store `session["transactionId"]` against your order, then hand the
+two cashier values to the page:
+
+```html
+<div id="checkout"></div>
+<script src="https://bp-checkout.dominaite.com/v2/launcher"
+        data-cashier-key="{{ cashier_key }}"
+        data-cashier-token="{{ cashier_token }}"></script>
+```
+
+HTML-escape both when templating (Jinja's autoescape does it for you). They are per-payment
+session values, not your credentials.
+
+That's the whole integration: the session call, the script tag, and your domain bound to your
+checkout by Dominaite during onboarding.
+
+## Amounts are minor units
+
+`amount` is always an integer in the currency's minor unit: `2500` is 25.00 EUR. A float or a
+string raises `ValueError` before anything is sent. The amount is locked server-side - what you
+pass here is what gets charged; nothing in the browser can change it.
+
+## Retries and double-charges
+
+Every `create_checkout_session` call carries an idempotency key (auto-generated, or pass your
+own as `idempotency_key`). Retrying with the same key never opens a second payment - on a
+timeout, retry with the same key rather than generating a new one.
+
+There is a helper that does exactly that:
+
+```python
+session = client.create_checkout_session_with_retry(
+    amount=2500,
+    currency="EUR",
+    order_reference="order-1042",
+    max_attempts=3,
+)
+```
+
+It retries only `TransportError` (network failures, 5xx, `MERCHANT_API_UNAVAILABLE`), reuses the
+one key across all attempts, and backs off between them. Refusals and authentication failures
+are raised immediately.
+
+## Sessions expire
+
+A session is valid for 2 hours. If the payer comes back later, create a new session.
+
+## Status polling
+
+```python
+status = client.get_status(session["transactionId"])
+# {"transactionId": ..., "orderReference": "order-1042", "status": "succeeded",
+#  "amount": 2500, "currency": "EUR", ...}
+```
+
+`status` is one of: `pending`, `processing`, `succeeded`, `failed`, `refunded`,
+`partially_refunded`, `cancelled`, `disputed`, `abandoned`. While the session is still payable
+the response also carries `expiresAt`; after that instant a `pending` session can only become
+`abandoned`. An unknown transaction id raises `ApiError` with `http_status == 404`.
+
+Poll after the payer returns to you, or on your order timeout - not in a tight loop; the
+endpoint is rate limited per key.
+
+## Errors
+
+| Exception | Means | Retry? |
+|---|---|---|
+| `AuthenticationError` | Bad credentials, bad signature, clock skew, IP not allowlisted | No - fix config |
+| `CheckoutRefusedError` | The gateway refused to open the session (`error_code`) | Depends on the code |
+| `ApiError` | Unexpected response, or a 4xx like an unknown transaction id (`http_status`) | No |
+| `TransportError` | Network failure or 5xx; you don't know if it landed | Yes, same idempotency key |
+
+All four inherit from `DominaiteError` if you only care that the call failed.
+
+## Running the tests
+
+```bash
+python -m venv .venv && .venv/bin/pip install pytest
+.venv/bin/python -m pytest
+```
+
+`tests/test_signing.py` reproduces the signing test vector published on the dashboard's
+Website-integration tab. If it ever fails, the SDK cannot authenticate - fix the signing, never
+the expected value.

dominaite-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# PyPI name settled as "dominaite" (verified free 2026-08-17); matches the import name.
+name = "dominaite"
+version = "0.1.0"
+description = "Server-side Python client for the Dominaite merchant API: create hosted checkout sessions from your own backend."
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+readme = "README.md"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dominaite"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dominaite-0.1.0/src/dominaite/__init__.py

@@ -0,0 +1,29 @@
+"""Server-side Python client for the Dominaite merchant API."""
+
+from .client import (
+    DEFAULT_BASE_URL,
+    SESSIONS_PATH,
+    DominaiteClient,
+    __version__,
+    sign_request,
+)
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    CheckoutRefusedError,
+    DominaiteError,
+    TransportError,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "SESSIONS_PATH",
+    "ApiError",
+    "AuthenticationError",
+    "CheckoutRefusedError",
+    "DominaiteClient",
+    "DominaiteError",
+    "TransportError",
+    "__version__",
+    "sign_request",
+]

dominaite-0.1.0/src/dominaite/client.py

@@ -0,0 +1,328 @@
+"""Server-side client for the Dominaite merchant API."""
+
+import hashlib
+import hmac
+import json
+import re
+import secrets
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Mapping, Optional
+
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    CheckoutRefusedError,
+    TransportError,
+)
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.dominaite.com/payments"
+SESSIONS_PATH = "/merchant-api/bridgerpay/checkout/sessions"
+DEFAULT_TIMEOUT_SECONDS = 45.0  # serverless cold starts hit 10+s on dev; 15s was a coin flip
+
+_TRANSACTION_ID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+)
+
+
+def sign_request(
+    secret: str,
+    timestamp: str,
+    method: str,
+    path: str,
+    idempotency_key: str,
+    body: str,
+) -> str:
+    """Build the ``X-Signature`` value for one request.
+
+    Lowercase hex HMAC-SHA256 over
+    ``"{timestamp}\\n{METHOD}\\n{path}\\n{idempotencyKey}\\n{sha256hex(body)}"``.
+
+    The idempotency key is INSIDE the signature, so a captured request cannot be
+    replayed with a different key to mint extra sessions. The server rejects
+    timestamps more than 5 minutes off - keep your server clock on NTP.
+
+    Exposed so you can pin it in your own test against the published vector.
+    """
+    body_hash = hashlib.sha256(body.encode("utf-8")).hexdigest()
+    payload = "\n".join([timestamp, method.upper(), path, idempotency_key, body_hash])
+    return hmac.new(
+        secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256
+    ).hexdigest()
+
+
+class DominaiteClient:
+    """Server-side client for the Dominaite merchant API.
+
+    Keep your API secret on the server. Never ship it to a browser, never commit it,
+    never log it. Card details never touch your backend or this SDK - the payer enters
+    them inside the hosted checkout widget.
+
+    Usage::
+
+        client = DominaiteClient(os.environ["DOMINAITE_KEY_ID"], os.environ["DOMINAITE_SECRET"])
+        session = client.create_checkout_session(
+            amount=2500,              # minor units: 25.00 EUR
+            currency="EUR",
+            order_reference="order-1042",
+            customer={"firstName": "Ana", "lastName": "K", "email": "ana@example.com"},
+        )
+        # Hand session["cashierKey"] + session["cashierToken"] to the embed snippet.
+    """
+
+    def __init__(
+        self,
+        key_id: str,
+        secret: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        """
+        :param key_id: Your API key id (``dmk_...``), from the Dominaite dashboard.
+        :param secret: Your API secret (``dms_...``). Server-side only.
+        :param base_url: Override for non-production environments.
+        :param timeout: Per-request socket timeout in seconds.
+        """
+        if not key_id.startswith("dmk_"):
+            raise ValueError("key_id must start with dmk_")
+        if not secret.startswith("dms_"):
+            raise ValueError("secret must start with dms_")
+        self._key_id = key_id
+        self._secret = secret
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def create_checkout_session(
+        self,
+        amount: int,
+        currency: str,
+        order_reference: str,
+        customer: Optional[Mapping[str, Any]] = None,
+        country: Optional[str] = None,
+        language: Optional[str] = None,
+        theme: Optional[str] = None,
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a hosted checkout session for one payment.
+
+        :param amount: Integer in MINOR units (2500 = 25.00 EUR). Never a float.
+        :param currency: ISO 4217 code.
+        :param order_reference: Your own order id, 100 chars or fewer.
+        :param customer: ``{"firstName", "lastName", "email", "phone"}``. Pass everything
+            you already know - prefilled fields are hidden from the payer, so the
+            checkout form stays short.
+        :param country: ISO 3166-1 alpha-2.
+        :param language: ISO 639-1, the widget UI language.
+        :param theme: ``light``, ``dark``, or ``bright``.
+        :param description: Free-text description shown on the checkout.
+        :param idempotency_key: Auto-generated when omitted. Retrying with the same key
+            never creates a second payment.
+        :returns: ``{"transactionId", "orderId", "cashierKey", "cashierToken", "amount",
+            "currency", "expiresAt"}``.
+
+        :raises AuthenticationError: Wrong/revoked credentials or bad signature
+            (fix config; do not retry).
+        :raises CheckoutRefusedError: The gateway refused the session (inspect
+            ``error_code``).
+        :raises ApiError: Unexpected API response.
+        :raises TransportError: Network-level failure (safe to retry WITH the same
+            ``idempotency_key``).
+        """
+        # bool is a subclass of int in Python, so True would otherwise sail through
+        # and get serialized as `true`.
+        if isinstance(amount, bool) or not isinstance(amount, int) or amount <= 0:
+            raise ValueError(
+                "amount must be a positive integer in MINOR units (e.g. 2500 for 25.00 EUR)"
+            )
+        if not currency:
+            raise ValueError("currency is required")
+        if not order_reference:
+            raise ValueError("order_reference is required")
+
+        key = idempotency_key if idempotency_key is not None else secrets.token_hex(16)
+        if not isinstance(key, str) or not key or len(key) > 100:
+            raise ValueError(
+                "idempotency_key must be a non-empty string of at most 100 characters"
+            )
+
+        body: Dict[str, Any] = {
+            "amount": amount,
+            "currency": currency,
+            "orderReference": order_reference,
+        }
+        if customer is not None:
+            body["customer"] = dict(customer)
+        if country is not None:
+            body["country"] = country
+        if language is not None:
+            body["language"] = language
+        if theme is not None:
+            body["theme"] = theme
+        if description is not None:
+            body["description"] = description
+
+        response = self._request("POST", SESSIONS_PATH, body, key)
+
+        if response.get("success") is not True or "checkout" not in response:
+            raise CheckoutRefusedError(
+                str(response.get("errorCode") or "UNKNOWN"),
+                str(response.get("errorMessage") or "The checkout session was refused."),
+            )
+
+        return response["checkout"]
+
+    def create_checkout_session_with_retry(
+        self,
+        max_attempts: int = 3,
+        backoff_seconds: float = 0.5,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Create a session, retrying transport failures with the SAME idempotency key.
+
+        A ``TransportError`` (network blip, 5xx, ``MERCHANT_API_UNAVAILABLE``) leaves you
+        not knowing whether the request landed. Reusing the key is what makes the retry
+        safe: the server returns the original session instead of opening a second one.
+        Generating a fresh key here would be the double-charge bug this method exists to
+        prevent.
+
+        Refusals and authentication failures are raised immediately - retrying them just
+        burns time.
+
+        :param max_attempts: Total attempts including the first one.
+        :param backoff_seconds: Base delay; doubles after each failed attempt.
+        :param kwargs: Passed straight to :meth:`create_checkout_session`.
+        """
+        if max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+
+        kwargs.setdefault("idempotency_key", secrets.token_hex(16))
+
+        delay = backoff_seconds
+        for attempt in range(1, max_attempts + 1):
+            try:
+                return self.create_checkout_session(**kwargs)
+            except TransportError:
+                if attempt == max_attempts:
+                    raise
+                if delay > 0:
+                    time.sleep(delay)
+                delay *= 2
+
+        raise AssertionError("unreachable")
+
+    def get_status(self, transaction_id: str) -> Dict[str, Any]:
+        """Read the payment status of one of your checkout sessions.
+
+        Status values: ``pending``, ``processing``, ``succeeded``, ``failed``,
+        ``refunded``, ``partially_refunded``, ``cancelled``, ``disputed``,
+        ``abandoned``. While a session is still payable the response carries
+        ``expiresAt``; amounts are integers in MINOR units.
+
+        :param transaction_id: The ``transactionId`` from
+            :meth:`create_checkout_session`.
+
+        :raises AuthenticationError: Wrong/revoked credentials or bad signature.
+        :raises ApiError: Unknown transaction id (HTTP 404) or unexpected response.
+        :raises TransportError: Network-level failure (safe to retry).
+        """
+        normalized = transaction_id.strip().lower()
+        if not _TRANSACTION_ID_RE.match(normalized):
+            raise ValueError(
+                "transaction_id must be the UUID returned by create_checkout_session()"
+            )
+
+        return self._request("GET", SESSIONS_PATH + "/" + normalized, None, "")
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]],
+        idempotency_key: str,
+    ) -> Dict[str, Any]:
+        """Sign and send one request.
+
+        ``body`` is None for GET: an empty body (and an empty idempotency key) is what
+        gets signed.
+        """
+        if body is None:
+            payload = ""
+        else:
+            # Compact separators and no ASCII escaping: the bytes we hash must be the
+            # exact bytes we send, so the JSON is serialized once and reused.
+            payload = json.dumps(body, separators=(",", ":"), ensure_ascii=False)
+
+        timestamp = str(int(time.time()))
+        signature = sign_request(
+            self._secret, timestamp, method, path, idempotency_key, payload
+        )
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-Api-Key-Id": self._key_id,
+            "X-Timestamp": timestamp,
+            "X-Signature": signature,
+            # Some edges block requests without a real User-Agent - always send one.
+            "User-Agent": "dominaite-python/" + __version__,
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        data = payload.encode("utf-8") if body is not None else None
+        request = urllib.request.Request(
+            self._base_url + path, data=data, headers=headers, method=method
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                status = response.status
+                raw = response.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as error:
+            # 4xx/5xx: the body still carries the machine-readable code.
+            status = error.code
+            raw = error.read().decode("utf-8", errors="replace")
+        except (urllib.error.URLError, OSError) as error:
+            raise TransportError(
+                "Could not reach the Dominaite API: {0}".format(error)
+            ) from error
+
+        try:
+            decoded = json.loads(raw)
+        except ValueError:
+            decoded = None
+        if not isinstance(decoded, dict):
+            raise ApiError(status, "The API returned a non-JSON response")
+
+        # The gateway wraps responses as { success, data, ... }; unwrap when present.
+        # Error responses carry the machine-readable code at error.code.
+        inner = decoded.get("data")
+        result = inner if isinstance(inner, dict) else decoded
+        envelope_error = decoded.get("error")
+        if not isinstance(envelope_error, dict):
+            envelope_error = {}
+
+        if status in (401, 403):
+            raise AuthenticationError(
+                str(result.get("errorCode") or envelope_error.get("code") or "UNAUTHORIZED"),
+                "Authentication failed - check your key id, secret, and server clock.",
+            )
+        if status >= 500:
+            raise TransportError(
+                "The Dominaite API is unavailable (HTTP {0}); "
+                "retry with the same idempotency key.".format(status)
+            )
+        if status >= 400:
+            raise ApiError(
+                status,
+                str(
+                    result.get("errorMessage")
+                    or envelope_error.get("message")
+                    or "Request rejected"
+                ),
+            )
+
+        return result

dominaite-0.1.0/src/dominaite/exceptions.py

@@ -0,0 +1,63 @@
+"""Exceptions raised by the Dominaite merchant API client.
+
+The split matters when you write your error handling: a CheckoutRefused means the
+gateway understood you and said no, a TransportError means you do not know whether
+the request landed. Only the second one is safe to retry.
+"""
+
+
+class DominaiteError(Exception):
+    """Base class for every error this SDK raises.
+
+    Catch this if you only care that the payment call failed. Catch the subclasses
+    when you want to branch on why.
+    """
+
+
+class ApiError(DominaiteError):
+    """The API answered, but with an unexpected or rejecting response."""
+
+    def __init__(self, http_status: int, message: str) -> None:
+        super().__init__(message)
+        self.http_status = http_status
+
+
+class AuthenticationError(DominaiteError):
+    """The API rejected your credentials or signature.
+
+    Not retryable - fix the key id, secret, or server clock. Machine-readable code
+    on ``error_code``:
+
+    - ``INVALID_API_KEY``: wrong or revoked key id.
+    - ``INVALID_SIGNATURE``: your signing is wrong; re-run the test vector.
+    - ``TIMESTAMP_OUT_OF_RANGE``: server clock is off; fix NTP, do not retry-loop.
+    - ``IP_NOT_ALLOWED``: this key is locked to addresses that don't include yours.
+    """
+
+    def __init__(self, error_code: str, message: str) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class CheckoutRefusedError(DominaiteError):
+    """The gateway understood the request but refused to open a checkout session.
+
+    Branch on ``error_code``:
+
+    - ``PAYMENT_PROCESSING_UNAVAILABLE``: card payments are off right now; retry later.
+    - ``DUPLICATE_REQUEST``: a session for this idempotency key is already open.
+    - ``ALREADY_PROCESSED``: this idempotency key's payment already completed.
+    - ``IDEMPOTENCY_KEY_REUSED``: same key sent with a DIFFERENT body; use a fresh key.
+    """
+
+    def __init__(self, error_code: str, message: str) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class TransportError(DominaiteError):
+    """Network-level failure or a 5xx.
+
+    The request may or may not have reached the API. Safe to retry WITH THE SAME
+    idempotency key; a retried key never creates a second payment.
+    """

dominaite-0.1.0/tests/conftest.py

@@ -0,0 +1,5 @@
+import sys
+from pathlib import Path
+
+# Run the suite straight from a checkout, without installing the package first.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))

dominaite-0.1.0/tests/test_client.py

@@ -0,0 +1,422 @@
+"""Contract tests for DominaiteClient: what it sends, and how it classifies answers."""
+
+import hashlib
+import io
+import json
+import urllib.error
+import urllib.request
+
+import pytest
+
+from dominaite import (
+    SESSIONS_PATH,
+    ApiError,
+    AuthenticationError,
+    CheckoutRefusedError,
+    DominaiteClient,
+    TransportError,
+    sign_request,
+)
+
+KEY_ID = "dmk_0123456789abcdef0123456789abcdef"
+SECRET = "dms_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+BASE_URL = "https://api.example.test/payments"
+TRANSACTION_ID = "11111111-2222-4333-8444-555555555555"
+
+EMPTY_SHA256 = hashlib.sha256(b"").hexdigest()
+
+CHECKOUT = {
+    "transactionId": TRANSACTION_ID,
+    "orderId": "ord_1",
+    "cashierKey": "ck_1",
+    "cashierToken": "ct_1",
+    "amount": 2500,
+    "currency": "EUR",
+    "expiresAt": "2026-08-16T12:00:00Z",
+}
+
+
+class _Response:
+    def __init__(self, status, payload):
+        self.status = status
+        self._body = json.dumps(payload).encode("utf-8")
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+class _Recorder:
+    """Stands in for urlopen and records every request the client builds."""
+
+    def __init__(self, *outcomes):
+        self.outcomes = list(outcomes)
+        self.requests = []
+
+    def __call__(self, request, timeout=None):
+        self.requests.append(request)
+        outcome = self.outcomes.pop(0) if len(self.outcomes) > 1 else self.outcomes[0]
+        if isinstance(outcome, Exception):
+            raise outcome
+        status, payload = outcome
+        if status >= 400:
+            raise urllib.error.HTTPError(
+                request.full_url,
+                status,
+                "error",
+                {},
+                io.BytesIO(json.dumps(payload).encode("utf-8")),
+            )
+        return _Response(status, payload)
+
+    @property
+    def last(self):
+        return self.requests[-1]
+
+
+@pytest.fixture
+def client():
+    return DominaiteClient(KEY_ID, SECRET, base_url=BASE_URL)
+
+
+@pytest.fixture
+def urlopen(monkeypatch):
+    def install(*outcomes):
+        recorder = _Recorder(*outcomes)
+        monkeypatch.setattr(urllib.request, "urlopen", recorder)
+        return recorder
+
+    return install
+
+
+def _ok():
+    return (200, {"success": True, "checkout": CHECKOUT})
+
+
+def _headers(request):
+    # urllib title-cases header names on the Request object.
+    return {name.lower(): value for name, value in request.headers.items()}
+
+
+# --- constructor -------------------------------------------------------------
+
+
+def test_rejects_key_id_without_dmk_prefix():
+    with pytest.raises(ValueError, match="dmk_"):
+        DominaiteClient("nope", SECRET)
+
+
+def test_rejects_secret_without_dms_prefix():
+    with pytest.raises(ValueError, match="dms_"):
+        DominaiteClient(KEY_ID, "nope")
+
+
+# --- what goes on the wire ---------------------------------------------------
+
+
+def test_post_sends_signed_headers_and_compact_json(client, urlopen):
+    recorder = urlopen(_ok())
+
+    client.create_checkout_session(
+        amount=2500,
+        currency="EUR",
+        order_reference="order-1042",
+        idempotency_key="00000000-0000-4000-8000-000000000001",
+    )
+
+    request = recorder.last
+    headers = _headers(request)
+    assert request.full_url == BASE_URL + SESSIONS_PATH
+    assert request.get_method() == "POST"
+    assert headers["x-api-key-id"] == KEY_ID
+    assert headers["idempotency-key"] == "00000000-0000-4000-8000-000000000001"
+    assert headers["content-type"] == "application/json"
+
+    body = request.data.decode("utf-8")
+    assert body == '{"amount":2500,"currency":"EUR","orderReference":"order-1042"}'
+
+    expected = sign_request(
+        SECRET,
+        headers["x-timestamp"],
+        "POST",
+        SESSIONS_PATH,
+        "00000000-0000-4000-8000-000000000001",
+        body,
+    )
+    assert headers["x-signature"] == expected
+
+
+def test_post_reproduces_the_published_vector_end_to_end(client, urlopen, monkeypatch):
+    """The signature the client actually puts on the wire, against the published vector.
+
+    test_signing.py pins the sign_request() function; this pins the whole path -
+    argument order, JSON serialization, header assembly - to the same answer.
+    """
+    monkeypatch.setattr("dominaite.client.time.time", lambda: 1755302400)
+    recorder = urlopen(_ok())
+
+    client.create_checkout_session(
+        amount=2500,
+        currency="EUR",
+        order_reference="order-1042",
+        idempotency_key="00000000-0000-4000-8000-000000000001",
+    )
+
+    headers = _headers(recorder.last)
+    assert headers["x-timestamp"] == "1755302400"
+    assert (
+        headers["x-signature"]
+        == "95759958a0a0a9bd3e6e37101c01e8e7fee1166406e4ac2ff488764f5f742cbf"
+    )
+
+
+def test_get_status_signs_empty_idempotency_key_and_empty_body(client, urlopen):
+    recorder = urlopen((200, {"transactionId": TRANSACTION_ID, "status": "succeeded"}))
+
+    client.get_status(TRANSACTION_ID)
+
+    request = recorder.last
+    headers = _headers(request)
+    path = SESSIONS_PATH + "/" + TRANSACTION_ID
+
+    assert request.get_method() == "GET"
+    assert request.data is None
+    assert "idempotency-key" not in headers
+
+    # The signed payload uses an EMPTY idempotency key and the hash of an EMPTY body.
+    expected = sign_request(SECRET, headers["x-timestamp"], "GET", path, "", "")
+    assert headers["x-signature"] == expected
+
+    payload = "\n".join([headers["x-timestamp"], "GET", path, "", EMPTY_SHA256])
+    assert payload.count("\n") == 4
+
+
+def test_get_status_normalizes_transaction_id_casing(client, urlopen):
+    recorder = urlopen((200, {"transactionId": TRANSACTION_ID}))
+
+    client.get_status("  " + TRANSACTION_ID.upper() + "  ")
+
+    assert recorder.last.full_url.endswith(SESSIONS_PATH + "/" + TRANSACTION_ID)
+
+
+def test_get_status_rejects_non_uuid(client):
+    with pytest.raises(ValueError, match="UUID"):
+        client.get_status("order-1042")
+
+
+def test_optional_fields_are_omitted_when_not_passed(client, urlopen):
+    recorder = urlopen(_ok())
+
+    client.create_checkout_session(
+        amount=2500,
+        currency="EUR",
+        order_reference="order-1042",
+        customer={"firstName": "Ana", "email": "ana@example.com"},
+        language="bg",
+    )
+
+    body = json.loads(recorder.last.data.decode("utf-8"))
+    assert body["customer"] == {"firstName": "Ana", "email": "ana@example.com"}
+    assert body["language"] == "bg"
+    assert "theme" not in body
+    assert "country" not in body
+    assert "description" not in body
+
+
+def test_generates_an_idempotency_key_when_none_is_given(client, urlopen):
+    recorder = urlopen(_ok())
+
+    client.create_checkout_session(amount=2500, currency="EUR", order_reference="o-1")
+    client.create_checkout_session(amount=2500, currency="EUR", order_reference="o-2")
+
+    first = _headers(recorder.requests[0])["idempotency-key"]
+    second = _headers(recorder.requests[1])["idempotency-key"]
+    assert first and second and first != second
+
+
+# --- amounts -----------------------------------------------------------------
+
+
+@pytest.mark.parametrize("amount", [25.0, "2500", 0, -1, True])
+def test_amount_must_be_a_positive_integer_in_minor_units(client, amount):
+    with pytest.raises(ValueError, match="MINOR units"):
+        client.create_checkout_session(
+            amount=amount, currency="EUR", order_reference="order-1042"
+        )
+
+
+# --- refusal vs transport ----------------------------------------------------
+
+
+def test_business_refusal_raises_checkout_refused_with_the_error_code(client, urlopen):
+    urlopen(
+        (
+            200,
+            {
+                "success": False,
+                "errorCode": "PAYMENT_PROCESSING_UNAVAILABLE",
+                "errorMessage": "Card payments are off",
+            },
+        )
+    )
+
+    with pytest.raises(CheckoutRefusedError) as caught:
+        client.create_checkout_session(
+            amount=2500, currency="EUR", order_reference="order-1042"
+        )
+
+    assert caught.value.error_code == "PAYMENT_PROCESSING_UNAVAILABLE"
+
+
+def test_503_raises_transport_not_refusal(client, urlopen):
+    urlopen((503, {"errorCode": "MERCHANT_API_UNAVAILABLE"}))
+
+    with pytest.raises(TransportError):
+        client.create_checkout_session(
+            amount=2500, currency="EUR", order_reference="order-1042"
+        )
+
+
+def test_network_failure_raises_transport(client, urlopen):
+    urlopen(urllib.error.URLError("connection reset"))
+
+    with pytest.raises(TransportError):
+        client.create_checkout_session(
+            amount=2500, currency="EUR", order_reference="order-1042"
+        )
+
+
+@pytest.mark.parametrize(
+    "code",
+    ["INVALID_API_KEY", "INVALID_SIGNATURE", "TIMESTAMP_OUT_OF_RANGE", "IP_NOT_ALLOWED"],
+)
+def test_401_raises_authentication_with_the_error_code(client, urlopen, code):
+    urlopen((401, {"errorCode": code}))
+
+    with pytest.raises(AuthenticationError) as caught:
+        client.create_checkout_session(
+            amount=2500, currency="EUR", order_reference="order-1042"
+        )
+
+    assert caught.value.error_code == code
+
+
+def test_422_key_reuse_raises_api_error_not_transport(client, urlopen):
+    urlopen((422, {"errorCode": "IDEMPOTENCY_KEY_REUSED", "errorMessage": "Use a fresh key"}))
+
+    with pytest.raises(ApiError) as caught:
+        client.create_checkout_session(
+            amount=2500, currency="EUR", order_reference="order-1042"
+        )
+
+    assert caught.value.http_status == 422
+
+
+def test_non_json_response_raises_api_error(client, urlopen, monkeypatch):
+    class _Garbage(_Response):
+        def read(self):
+            return b"<html>502 Bad Gateway</html>"
+
+    monkeypatch.setattr(
+        urllib.request, "urlopen", lambda request, timeout=None: _Garbage(200, {})
+    )
+
+    with pytest.raises(ApiError):
+        client.create_checkout_session(
+            amount=2500, currency="EUR", order_reference="order-1042"
+        )
+
+
+def test_envelope_wrapped_response_is_unwrapped(client, urlopen):
+    urlopen((200, {"success": True, "data": {"success": True, "checkout": CHECKOUT}}))
+
+    session = client.create_checkout_session(
+        amount=2500, currency="EUR", order_reference="order-1042"
+    )
+
+    assert session == CHECKOUT
+
+
+# --- retry with the same key -------------------------------------------------
+
+
+def test_retry_helper_reuses_the_same_idempotency_key(client, urlopen):
+    recorder = urlopen((503, {"errorCode": "MERCHANT_API_UNAVAILABLE"}), _ok())
+
+    session = client.create_checkout_session_with_retry(
+        amount=2500,
+        currency="EUR",
+        order_reference="order-1042",
+        max_attempts=2,
+        backoff_seconds=0,
+    )
+
+    assert session == CHECKOUT
+    assert len(recorder.requests) == 2
+    keys = {_headers(r)["idempotency-key"] for r in recorder.requests}
+    assert len(keys) == 1, "a retry must not mint a new key - that is the double-charge bug"
+
+
+def test_retry_helper_honours_a_caller_supplied_key(client, urlopen):
+    recorder = urlopen((503, {}), _ok())
+
+    client.create_checkout_session_with_retry(
+        amount=2500,
+        currency="EUR",
+        order_reference="order-1042",
+        idempotency_key="my-own-key",
+        max_attempts=2,
+        backoff_seconds=0,
+    )
+
+    assert all(_headers(r)["idempotency-key"] == "my-own-key" for r in recorder.requests)
+
+
+def test_retry_helper_does_not_retry_a_refusal(client, urlopen):
+    recorder = urlopen((200, {"success": False, "errorCode": "ALREADY_PROCESSED"}))
+
+    with pytest.raises(CheckoutRefusedError):
+        client.create_checkout_session_with_retry(
+            amount=2500,
+            currency="EUR",
+            order_reference="order-1042",
+            max_attempts=3,
+            backoff_seconds=0,
+        )
+
+    assert len(recorder.requests) == 1
+
+
+def test_retry_helper_does_not_retry_an_auth_failure(client, urlopen):
+    recorder = urlopen((401, {"errorCode": "INVALID_SIGNATURE"}))
+
+    with pytest.raises(AuthenticationError):
+        client.create_checkout_session_with_retry(
+            amount=2500,
+            currency="EUR",
+            order_reference="order-1042",
+            max_attempts=3,
+            backoff_seconds=0,
+        )
+
+    assert len(recorder.requests) == 1
+
+
+def test_retry_helper_gives_up_and_raises_the_transport_error(client, urlopen):
+    recorder = urlopen(urllib.error.URLError("down"))
+
+    with pytest.raises(TransportError):
+        client.create_checkout_session_with_retry(
+            amount=2500,
+            currency="EUR",
+            order_reference="order-1042",
+            max_attempts=3,
+            backoff_seconds=0,
+        )
+
+    assert len(recorder.requests) == 3

dominaite-0.1.0/tests/test_signing.py

@@ -0,0 +1,63 @@
+"""Known-answer tests for the request signature.
+
+The vector is the one published on the Website-integration tab and pinned in
+web-platform's `SIGNING_TEST_VECTOR`. If these fail, the SDK cannot authenticate
+against the gateway - fix the signing, never the expected value.
+
+The secret below is a dummy from the public docs. It authenticates nothing.
+"""
+
+import hashlib
+
+from dominaite import SESSIONS_PATH, sign_request
+
+SECRET = "dms_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+TIMESTAMP = "1755302400"
+IDEMPOTENCY_KEY = "00000000-0000-4000-8000-000000000001"
+BODY = '{"amount":2500,"currency":"EUR","orderReference":"order-1042"}'
+EXPECTED_BODY_SHA256 = "aa3edd72cd1829f4e053abb048b08c1ae91c2d67b08955997c4b6c4dab4f98ff"
+EXPECTED_SIGNATURE = "95759958a0a0a9bd3e6e37101c01e8e7fee1166406e4ac2ff488764f5f742cbf"
+
+
+def test_body_hash_matches_published_vector():
+    assert hashlib.sha256(BODY.encode("utf-8")).hexdigest() == EXPECTED_BODY_SHA256
+
+
+def test_post_signature_matches_published_vector():
+    signature = sign_request(
+        secret=SECRET,
+        timestamp=TIMESTAMP,
+        method="POST",
+        path=SESSIONS_PATH,
+        idempotency_key=IDEMPOTENCY_KEY,
+        body=BODY,
+    )
+
+    assert signature == EXPECTED_SIGNATURE
+
+
+def test_signature_is_lowercase_hex():
+    signature = sign_request(SECRET, TIMESTAMP, "POST", SESSIONS_PATH, IDEMPOTENCY_KEY, BODY)
+
+    assert signature == signature.lower()
+    assert len(signature) == 64
+
+
+def test_method_is_uppercased_before_signing():
+    lower = sign_request(SECRET, TIMESTAMP, "post", SESSIONS_PATH, IDEMPOTENCY_KEY, BODY)
+
+    assert lower == EXPECTED_SIGNATURE
+
+
+def test_changing_the_idempotency_key_changes_the_signature():
+    """The key is inside the signature, which is what makes replay harmless."""
+    other = sign_request(
+        SECRET,
+        TIMESTAMP,
+        "POST",
+        SESSIONS_PATH,
+        "00000000-0000-4000-8000-000000000002",
+        BODY,
+    )
+
+    assert other != EXPECTED_SIGNATURE