kuti-pe 1.0.0__tar.gz

kuti_pe-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

kuti_pe-1.0.0/LICENSE

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

kuti_pe-1.0.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: kuti-pe
+Version: 1.0.0
+Summary: SDK oficial de KUTI para Python — crea checkout sessions, consulta pagos y verifica webhooks.
+Project-URL: Homepage, https://docs.kuti.pe
+Project-URL: Documentation, https://docs.kuti.pe/sdks
+Project-URL: Repository, https://github.com/kuti-pe/kuti-python
+Project-URL: Issues, https://github.com/kuti-pe/kuti-python/issues
+Author-email: KUTI <soporte@kuti.pe>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: checkout,kuti,payments,peru,qr,yape
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kuti-pe
+
+SDK oficial de KUTI para Python. Crea sesiones de checkout, consulta el estado de un pago y verifica webhooks — sin reimplementar auth, manejo de errores ni firma HMAC a mano.
+
+> **Solo servidor.** Este paquete usa tu secret key (`kuti_live_...` / `kuti_test_...`). Nunca lo importes en código que se sirva al navegador.
+
+## Instalación
+
+```bash
+pip install kuti-pe
+```
+
+## Quickstart
+
+```python
+import os
+from kuti import KutiClient
+
+kuti = KutiClient(os.environ["KUTI_SECRET_KEY"])
+
+# El monto SIEMPRE se resuelve en tu backend — nunca confíes en un monto
+# que te mande el navegador del comprador.
+session = kuti.checkout_sessions.create(
+    amount={"amount": "249.90", "currency": "PEN"},
+    payment_method_types=["INTEROPERABLE_QR", "BANK_TRANSFER"],
+    description="Zapatillas running talla 42",
+    customer={"name": "María López", "email": "maria@example.com"},
+    idempotency_key=f"order-{order_id}",  # evita duplicar el cobro si reintentas
+)
+
+# Envía session.checkout_url al frontend y ábrelo con Checkout.js:
+#   window.Kuti.open({ checkoutUrl: session.checkout_url, onSuccess, onFailure })
+```
+
+## Confirmar un pago (sin necesitar webhooks)
+
+`onSuccess` de Checkout.js corre en el navegador del comprador — no es confiable por sí solo. Vuelve a preguntarle a la API:
+
+```python
+intent = kuti.payment_intents.retrieve(payment_intent_id)
+if intent.status == "SUCCEEDED":
+    # entrega el producto / activa el servicio
+    pass
+```
+
+## Verificar un webhook
+
+```python
+from flask import Flask, request
+from kuti import verify_webhook_signature, KutiSignatureVerificationError
+import os
+
+app = Flask(__name__)
+
+@app.post("/webhooks/kuti")
+def kuti_webhook():
+    payload = request.get_data(as_text=True)  # body CRUDO, sin json.loads antes
+    try:
+        verify_webhook_signature(
+            payload,
+            request.headers["X-Kuti-Signature"],
+            request.headers["X-Kuti-Timestamp"],
+            os.environ["KUTI_WEBHOOK_SECRET"],
+        )
+    except KutiSignatureVerificationError:
+        return "Invalid signature", 400
+
+    event = request.get_json(force=True)
+    # payment.succeeded, checkout.session.completed, …
+    return "", 200
+```
+
+## Manejo de errores
+
+Todas las excepciones de la API extienden `KutiApiError` (`status`, `code`, `request_id`, `doc_url`, `details`):
+
+```python
+from kuti import KutiValidationError, KutiNotFoundError, KutiApiError
+
+try:
+    kuti.checkout_sessions.create(...)
+except KutiValidationError as err:
+    print(err.details)  # [ErrorDetail(field="amount.amount", ...)]
+except KutiNotFoundError:
+    pass
+except KutiApiError as err:
+    print(err.code, err.request_id)  # úsalo al reportar un bug a soporte
+```
+
+Los `GET` y los `POST` con `idempotency_key` se reintentan automáticamente en errores de red o `429`/`503`. Un `POST` sin `idempotency_key` nunca se reintenta, para no duplicar un cobro.
+
+## API
+
+- `KutiClient(secret_key, base_url=None)`
+- `kuti.checkout_sessions.create(*, amount, payment_method_types, …, idempotency_key=None)`
+- `kuti.payment_intents.retrieve(id)`
+- `verify_webhook_signature(payload, signature_header, timestamp_header, secret, tolerance_seconds=300)`
+
+## Requisitos
+
+Python 3.9+ · sin dependencias de runtime.

kuti_pe-1.0.0/README.md

@@ -0,0 +1,101 @@
+# kuti-pe
+
+SDK oficial de KUTI para Python. Crea sesiones de checkout, consulta el estado de un pago y verifica webhooks — sin reimplementar auth, manejo de errores ni firma HMAC a mano.
+
+> **Solo servidor.** Este paquete usa tu secret key (`kuti_live_...` / `kuti_test_...`). Nunca lo importes en código que se sirva al navegador.
+
+## Instalación
+
+```bash
+pip install kuti-pe
+```
+
+## Quickstart
+
+```python
+import os
+from kuti import KutiClient
+
+kuti = KutiClient(os.environ["KUTI_SECRET_KEY"])
+
+# El monto SIEMPRE se resuelve en tu backend — nunca confíes en un monto
+# que te mande el navegador del comprador.
+session = kuti.checkout_sessions.create(
+    amount={"amount": "249.90", "currency": "PEN"},
+    payment_method_types=["INTEROPERABLE_QR", "BANK_TRANSFER"],
+    description="Zapatillas running talla 42",
+    customer={"name": "María López", "email": "maria@example.com"},
+    idempotency_key=f"order-{order_id}",  # evita duplicar el cobro si reintentas
+)
+
+# Envía session.checkout_url al frontend y ábrelo con Checkout.js:
+#   window.Kuti.open({ checkoutUrl: session.checkout_url, onSuccess, onFailure })
+```
+
+## Confirmar un pago (sin necesitar webhooks)
+
+`onSuccess` de Checkout.js corre en el navegador del comprador — no es confiable por sí solo. Vuelve a preguntarle a la API:
+
+```python
+intent = kuti.payment_intents.retrieve(payment_intent_id)
+if intent.status == "SUCCEEDED":
+    # entrega el producto / activa el servicio
+    pass
+```
+
+## Verificar un webhook
+
+```python
+from flask import Flask, request
+from kuti import verify_webhook_signature, KutiSignatureVerificationError
+import os
+
+app = Flask(__name__)
+
+@app.post("/webhooks/kuti")
+def kuti_webhook():
+    payload = request.get_data(as_text=True)  # body CRUDO, sin json.loads antes
+    try:
+        verify_webhook_signature(
+            payload,
+            request.headers["X-Kuti-Signature"],
+            request.headers["X-Kuti-Timestamp"],
+            os.environ["KUTI_WEBHOOK_SECRET"],
+        )
+    except KutiSignatureVerificationError:
+        return "Invalid signature", 400
+
+    event = request.get_json(force=True)
+    # payment.succeeded, checkout.session.completed, …
+    return "", 200
+```
+
+## Manejo de errores
+
+Todas las excepciones de la API extienden `KutiApiError` (`status`, `code`, `request_id`, `doc_url`, `details`):
+
+```python
+from kuti import KutiValidationError, KutiNotFoundError, KutiApiError
+
+try:
+    kuti.checkout_sessions.create(...)
+except KutiValidationError as err:
+    print(err.details)  # [ErrorDetail(field="amount.amount", ...)]
+except KutiNotFoundError:
+    pass
+except KutiApiError as err:
+    print(err.code, err.request_id)  # úsalo al reportar un bug a soporte
+```
+
+Los `GET` y los `POST` con `idempotency_key` se reintentan automáticamente en errores de red o `429`/`503`. Un `POST` sin `idempotency_key` nunca se reintenta, para no duplicar un cobro.
+
+## API
+
+- `KutiClient(secret_key, base_url=None)`
+- `kuti.checkout_sessions.create(*, amount, payment_method_types, …, idempotency_key=None)`
+- `kuti.payment_intents.retrieve(id)`
+- `verify_webhook_signature(payload, signature_header, timestamp_header, secret, tolerance_seconds=300)`
+
+## Requisitos
+
+Python 3.9+ · sin dependencias de runtime.

kuti_pe-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kuti-pe"
+version = "1.0.0"
+description = "SDK oficial de KUTI para Python — crea checkout sessions, consulta pagos y verifica webhooks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+  { name = "KUTI", email = "soporte@kuti.pe" },
+]
+keywords = ["kuti", "payments", "peru", "yape", "qr", "checkout"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "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",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://docs.kuti.pe"
+Documentation = "https://docs.kuti.pe/sdks"
+Repository = "https://github.com/kuti-pe/kuti-python"
+Issues = "https://github.com/kuti-pe/kuti-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "respx>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kuti"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/kuti", "LICENSE", "README.md", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

kuti_pe-1.0.0/src/kuti/__init__.py

@@ -0,0 +1,43 @@
+"""SDK oficial de KUTI para Python."""
+
+from .client import KutiClient
+from .errors import (
+    KutiApiError,
+    KutiAuthenticationError,
+    KutiConflictError,
+    KutiConnectionError,
+    KutiNotFoundError,
+    KutiPermissionError,
+    KutiRateLimitError,
+    KutiSignatureVerificationError,
+    KutiValidationError,
+)
+from .types import (
+    CheckoutSession,
+    CheckoutSessionCustomer,
+    Money,
+    PaymentIntent,
+    PaymentMethodType,
+)
+from .webhooks import verify_webhook_signature
+
+__all__ = [
+    "KutiClient",
+    "Money",
+    "CheckoutSessionCustomer",
+    "CheckoutSession",
+    "PaymentIntent",
+    "PaymentMethodType",
+    "verify_webhook_signature",
+    "KutiApiError",
+    "KutiAuthenticationError",
+    "KutiPermissionError",
+    "KutiNotFoundError",
+    "KutiValidationError",
+    "KutiConflictError",
+    "KutiRateLimitError",
+    "KutiConnectionError",
+    "KutiSignatureVerificationError",
+]
+
+__version__ = "1.0.0"

kuti_pe-1.0.0/src/kuti/client.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional
+from .errors import KutiConnectionError, error_for_status
+from .resources.checkout_sessions import CheckoutSessionsResource
+from .resources.payment_intents import PaymentIntentsResource
+from .types import RequestOptions
+
+DEFAULT_BASE_URL = "https://api.kuti.pe/v1"
+_SECRET_KEY_PREFIXES = ("kuti_live_", "kuti_test_")
+_MAX_RETRIES = 2
+_RETRYABLE_STATUS = {429, 503}
+
+
+class KutiClient:
+    """Cliente HTTP central de KUTI.
+
+    Cuelgan de aquí los recursos (``checkout_sessions``, ``payment_intents``);
+    esta clase solo resuelve auth, reintentos y mapeo de errores.
+    """
+
+    def __init__(self, secret_key: str, *, base_url: Optional[str] = None) -> None:
+        if not any(secret_key.startswith(p) for p in _SECRET_KEY_PREFIXES):
+            raise ValueError(
+                "KutiClient expects a secret key (kuti_live_... / kuti_test_...), "
+                "not a publishable key."
+            )
+        self._secret_key = secret_key
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.checkout_sessions = CheckoutSessionsResource(self)
+        self.payment_intents = PaymentIntentsResource(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        opts: Optional[RequestOptions] = None,
+    ) -> Dict[str, Any]:
+        """Uso interno de los recursos — no lo llames directo."""
+        headers = {
+            "Authorization": f"Bearer {self._secret_key}",
+            "Accept": "application/json",
+            "User-Agent": "kuti-pe/1.0.0 (python)",
+        }
+        data: Optional[bytes] = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+        if opts and opts.idempotency_key:
+            headers["Idempotency-Key"] = opts.idempotency_key
+
+        # Solo se reintenta si el request es idempotente por diseño (GET) o el caller
+        # ya proveyó una Idempotency-Key — nunca un POST "a ciegas".
+        can_retry = method == "GET" or bool(opts and opts.idempotency_key)
+        max_attempts = _MAX_RETRIES + 1 if can_retry else 1
+
+        last_error: Optional[BaseException] = None
+        for attempt in range(max_attempts):
+            if attempt > 0:
+                time.sleep((2**attempt) * 0.2)
+            try:
+                req = urllib.request.Request(
+                    f"{self._base_url}{path}",
+                    data=data,
+                    headers=headers,
+                    method=method,
+                )
+                with urllib.request.urlopen(req, timeout=30) as resp:
+                    raw = resp.read().decode("utf-8")
+                    return json.loads(raw) if raw else {}
+            except urllib.error.HTTPError as exc:
+                envelope = _safe_parse_error(exc)
+                err_body = envelope.get("error") or {}
+                api_error = error_for_status(
+                    exc.code,
+                    code=err_body.get("code") or "UNKNOWN_ERROR",
+                    message=err_body.get("message")
+                    or envelope.get("message")
+                    or exc.reason,
+                    request_id=err_body.get("request_id"),
+                    doc_url=err_body.get("doc_url"),
+                    details=err_body.get("details"),
+                )
+                if can_retry and exc.code in _RETRYABLE_STATUS and attempt < _MAX_RETRIES:
+                    last_error = api_error
+                    continue
+                raise api_error from None
+            except urllib.error.URLError as exc:
+                last_error = KutiConnectionError("Could not reach the KUTI API.", exc)
+                if not can_retry:
+                    raise last_error from exc
+            except TimeoutError as exc:
+                last_error = KutiConnectionError("Could not reach the KUTI API.", exc)
+                if not can_retry:
+                    raise last_error from exc
+
+        assert last_error is not None
+        raise last_error
+
+
+def _safe_parse_error(exc: urllib.error.HTTPError) -> Dict[str, Any]:
+    try:
+        raw = exc.read().decode("utf-8")
+        parsed = json.loads(raw) if raw else {}
+        return parsed if isinstance(parsed, dict) else {}
+    except Exception:
+        return {}

kuti_pe-1.0.0/src/kuti/errors.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .types import ErrorDetail
+
+
+class KutiApiError(Exception):
+    """Error base de la API — cualquier respuesta HTTP != 2xx."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+        doc_url: Optional[str] = None,
+        details: Optional[List[Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.doc_url = doc_url
+        self.details: List[ErrorDetail] = []
+        for d in details or []:
+            if isinstance(d, dict):
+                self.details.append(
+                    ErrorDetail(
+                        field=d.get("field"),
+                        code=d.get("code"),
+                        message=d.get("message"),
+                    )
+                )
+
+
+class KutiAuthenticationError(KutiApiError):
+    """401 — secret key inválida, revocada o ausente."""
+
+
+class KutiPermissionError(KutiApiError):
+    """403 — key válida pero sin permiso."""
+
+
+class KutiNotFoundError(KutiApiError):
+    """404 — recurso inexistente o de otro merchant."""
+
+
+class KutiValidationError(KutiApiError):
+    """400 / 422 — request inválido. Revisa `.details`."""
+
+
+class KutiConflictError(KutiApiError):
+    """409 — conflicto de estado."""
+
+
+class KutiRateLimitError(KutiApiError):
+    """429 — demasiadas requests."""
+
+
+class KutiConnectionError(Exception):
+    """Fallo de red o timeout — no hubo respuesta HTTP de KUTI."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class KutiSignatureVerificationError(Exception):
+    """Firma de webhook inválida o timestamp fuera de tolerancia."""
+
+
+def error_for_status(
+    status: int,
+    *,
+    code: str,
+    message: str,
+    request_id: Optional[str] = None,
+    doc_url: Optional[str] = None,
+    details: Optional[List[Any]] = None,
+) -> KutiApiError:
+    kwargs = dict(
+        status=status,
+        code=code,
+        message=message,
+        request_id=request_id,
+        doc_url=doc_url,
+        details=details,
+    )
+    if status == 401:
+        return KutiAuthenticationError(**kwargs)
+    if status == 403:
+        return KutiPermissionError(**kwargs)
+    if status == 404:
+        return KutiNotFoundError(**kwargs)
+    if status in (400, 422):
+        return KutiValidationError(**kwargs)
+    if status == 409:
+        return KutiConflictError(**kwargs)
+    if status == 429:
+        return KutiRateLimitError(**kwargs)
+    return KutiApiError(**kwargs)

kuti_pe-1.0.0/src/kuti/py.typed

@@ -0,0 +1 @@
+# Marker for PEP 561 — typed package.

kuti_pe-1.0.0/src/kuti/resources/__init__.py

@@ -0,0 +1 @@
+# Resources package

kuti_pe-1.0.0/src/kuti/resources/checkout_sessions.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+
+from ..types import (
+    CheckoutSession,
+    CheckoutSessionCustomer,
+    Money,
+    PaymentMethodType,
+    RequestOptions,
+    money_from_api,
+    payment_method_from_api,
+)
+
+if TYPE_CHECKING:
+    from ..client import KutiClient
+
+
+class CheckoutSessionsResource:
+    def __init__(self, client: KutiClient) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        amount: Union[Money, Dict[str, str]],
+        payment_method_types: List[PaymentMethodType],
+        customer: Optional[Union[CheckoutSessionCustomer, Dict[str, Any]]] = None,
+        description: Optional[str] = None,
+        external_reference: Optional[str] = None,
+        success_url: Optional[str] = None,
+        expires_at: Optional[str] = None,
+        metadata: Optional[Dict[str, str]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> CheckoutSession:
+        """Crea una sesión de cargo único.
+
+        El monto SIEMPRE debe resolverse en tu backend. Pasa ``idempotency_key``
+        (ej. tu id de orden) para no duplicar el cobro al reintentar.
+        """
+        money = (
+            amount
+            if isinstance(amount, Money)
+            else Money(amount=str(amount["amount"]), currency=str(amount["currency"]))
+        )
+        cust_obj: Optional[CheckoutSessionCustomer] = None
+        if customer is not None:
+            if isinstance(customer, CheckoutSessionCustomer):
+                cust_obj = customer
+            else:
+                cust_obj = CheckoutSessionCustomer(
+                    id=customer.get("id"),
+                    external_id=customer.get("external_id"),
+                    name=customer.get("name"),
+                    email=customer.get("email"),
+                    phone=customer.get("phone"),
+                )
+
+        body: Dict[str, Any] = {
+            "amount": {"amount": money.amount, "currency": money.currency},
+            "payment_method_types": list(payment_method_types),
+        }
+        if cust_obj is not None:
+            cust: Dict[str, Any] = {}
+            if cust_obj.id is not None:
+                cust["id"] = cust_obj.id
+            if cust_obj.external_id is not None:
+                cust["external_id"] = cust_obj.external_id
+            if cust_obj.name is not None:
+                cust["name"] = cust_obj.name
+            if cust_obj.email is not None:
+                cust["email"] = cust_obj.email
+            if cust_obj.phone is not None:
+                cust["phone"] = cust_obj.phone
+            body["customer"] = cust
+        if description is not None:
+            body["description"] = description
+        if external_reference is not None:
+            body["external_reference"] = external_reference
+        if success_url is not None:
+            body["success_url"] = success_url
+        if expires_at is not None:
+            body["expires_at"] = expires_at
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        opts = RequestOptions(idempotency_key=idempotency_key) if idempotency_key else None
+        response = self._client.request("POST", "/checkout-sessions", body, opts)
+        return _from_api(response["data"])
+
+
+def _from_api(dto: Dict[str, Any]) -> CheckoutSession:
+    return CheckoutSession(
+        id=dto["id"],
+        merchant_id=dto["merchant_id"],
+        customer_id=dto.get("customer_id"),
+        payment_intent_id=dto["payment_intent_id"],
+        amount=money_from_api(dto["amount"]),
+        status=dto["status"],
+        description=dto.get("description"),
+        success_url=dto.get("success_url"),
+        client_secret=dto.get("client_secret"),
+        checkout_url=dto.get("checkout_url"),
+        payment_method=payment_method_from_api(dto.get("payment_method")),
+        expires_at=dto.get("expires_at"),
+        created_at=dto["created_at"],
+    )

kuti_pe-1.0.0/src/kuti/resources/payment_intents.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict
+from urllib.parse import quote
+
+from ..types import PaidWith, PaymentIntent, money_from_api, payment_method_from_api
+
+if TYPE_CHECKING:
+    from ..client import KutiClient
+
+
+class PaymentIntentsResource:
+    def __init__(self, client: KutiClient) -> None:
+        self._client = client
+
+    def retrieve(self, payment_intent_id: str) -> PaymentIntent:
+        """Consulta el estado real de un cobro.
+
+        Es la fuente de verdad — nunca confíes solo en un callback del frontend
+        (``onSuccess`` de Checkout.js). Verifica ``status == "SUCCEEDED"`` aquí
+        antes de entregar un producto o servicio.
+        """
+        response = self._client.request(
+            "GET",
+            f"/payment-intents/{quote(payment_intent_id, safe='')}",
+        )
+        return _from_api(response["data"])
+
+
+def _from_api(dto: Dict[str, Any]) -> PaymentIntent:
+    customer = dto.get("customer") or {}
+    customer_id = customer.get("id") if isinstance(customer, dict) else None
+    if customer_id is None:
+        customer_id = dto.get("customer_id")
+
+    paid_raw = dto.get("paid_with")
+    paid_with = None
+    if paid_raw:
+        paid_with = PaidWith(
+            method_type=paid_raw.get("method_type"),
+            paid_at=paid_raw.get("paid_at"),
+        )
+
+    return PaymentIntent(
+        id=dto["id"],
+        merchant_id=dto["merchant_id"],
+        livemode=dto.get("livemode"),
+        customer_id=customer_id,
+        amount=money_from_api(dto["amount"]),
+        status=dto["status"],
+        payment_method_types=dto.get("payment_method_types"),
+        payment_method=payment_method_from_api(dto.get("payment_method")),
+        paid_with=paid_with,
+        checkout_url=dto.get("checkout_url"),
+        expires_at=dto.get("expires_at"),
+        external_reference=dto.get("external_reference"),
+        description=dto.get("description"),
+        category_id=dto.get("category_id"),
+        metadata=dto.get("metadata"),
+        requires_customer_info=dto.get("requires_customer_info"),
+        created_at=dto["created_at"],
+    )

kuti_pe-1.0.0/src/kuti/types.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Literal, Optional
+
+PaymentMethodType = Literal["INTEROPERABLE_QR", "BANK_TRANSFER"]
+
+CheckoutSessionStatus = Literal["OPEN", "COMPLETED", "EXPIRED", "CANCELLED"]
+
+PaymentIntentStatus = Literal[
+    "REQUIRES_PAYMENT_METHOD",
+    "PENDING",
+    "PROCESSING",
+    "SUCCEEDED",
+    "FAILED",
+    "CANCELLED",
+    "EXPIRED",
+]
+
+
+@dataclass(frozen=True)
+class Money:
+    """Monto decimal como string. Nunca float."""
+
+    amount: str
+    currency: str
+
+
+@dataclass(frozen=True)
+class CheckoutSessionCustomer:
+    """Id de un Customer ya existente (cus_…). Si viene, se ignora el resto."""
+
+    id: Optional[str] = None
+    external_id: Optional[str] = None
+    name: Optional[str] = None
+    email: Optional[str] = None
+    phone: Optional[str] = None  # E.164
+
+
+@dataclass(frozen=True)
+class PaymentMethodQr:
+    type: Optional[PaymentMethodType] = None
+    payload: Optional[str] = None
+    image_url: Optional[str] = None
+    expires_at: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class PaymentMethodPaymentCode:
+    type: Optional[PaymentMethodType] = None
+    code: Optional[str] = None
+    expires_at: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class PaymentMethod:
+    qr: Optional[PaymentMethodQr] = None
+    payment_code: Optional[PaymentMethodPaymentCode] = None
+
+
+@dataclass(frozen=True)
+class PaidWith:
+    method_type: Optional[PaymentMethodType] = None
+    paid_at: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class CheckoutSession:
+    id: str
+    merchant_id: str
+    payment_intent_id: str
+    amount: Money
+    status: CheckoutSessionStatus
+    created_at: str
+    customer_id: Optional[str] = None
+    description: Optional[str] = None
+    success_url: Optional[str] = None
+    client_secret: Optional[str] = None
+    checkout_url: Optional[str] = None
+    payment_method: Optional[PaymentMethod] = None
+    expires_at: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class PaymentIntent:
+    id: str
+    merchant_id: str
+    amount: Money
+    status: PaymentIntentStatus
+    created_at: str
+    livemode: Optional[bool] = None
+    customer_id: Optional[str] = None
+    payment_method_types: Optional[List[PaymentMethodType]] = None
+    payment_method: Optional[PaymentMethod] = None
+    paid_with: Optional[PaidWith] = None
+    checkout_url: Optional[str] = None
+    expires_at: Optional[str] = None
+    external_reference: Optional[str] = None
+    description: Optional[str] = None
+    category_id: Optional[str] = None
+    metadata: Optional[Dict[str, str]] = None
+    requires_customer_info: Optional[bool] = None
+
+
+@dataclass
+class CreateCheckoutSessionParams:
+    amount: Money
+    payment_method_types: List[PaymentMethodType]
+    customer: Optional[CheckoutSessionCustomer] = None
+    description: Optional[str] = None
+    external_reference: Optional[str] = None
+    success_url: Optional[str] = None
+    expires_at: Optional[str] = None
+    metadata: Optional[Dict[str, str]] = None
+
+
+@dataclass(frozen=True)
+class RequestOptions:
+    """Evita duplicar la operación si el request se reintenta."""
+
+    idempotency_key: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ErrorDetail:
+    field: Optional[str] = None
+    code: Optional[str] = None
+    message: Optional[str] = None
+
+
+def money_from_api(raw: Dict[str, Any]) -> Money:
+    return Money(amount=str(raw["amount"]), currency=str(raw["currency"]))
+
+
+def payment_method_from_api(raw: Optional[Dict[str, Any]]) -> Optional[PaymentMethod]:
+    if not raw:
+        return None
+    qr_raw = raw.get("qr")
+    code_raw = raw.get("payment_code")
+    return PaymentMethod(
+        qr=(
+            PaymentMethodQr(
+                type=qr_raw.get("type"),
+                payload=qr_raw.get("payload"),
+                image_url=qr_raw.get("image_url"),
+                expires_at=qr_raw.get("expires_at"),
+            )
+            if qr_raw
+            else None
+        ),
+        payment_code=(
+            PaymentMethodPaymentCode(
+                type=code_raw.get("type"),
+                code=code_raw.get("code"),
+                expires_at=code_raw.get("expires_at"),
+            )
+            if code_raw
+            else None
+        ),
+    )

kuti_pe-1.0.0/src/kuti/webhooks.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+from .errors import KutiSignatureVerificationError
+
+_SIGNATURE_PREFIX = "v1="
+_DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def verify_webhook_signature(
+    payload: str | bytes,
+    signature_header: str,
+    timestamp_header: str,
+    secret: str,
+    tolerance_seconds: int = _DEFAULT_TOLERANCE_SECONDS,
+) -> None:
+    """Verifica la firma de un webhook de KUTI.
+
+    Recomputa ``HMAC_SHA256(secret, "<timestamp>.<body>")`` con el *payload* crudo
+    (el string exacto del body, SIN parsear a JSON primero) y lo compara en tiempo
+    constante contra el header ``X-Kuti-Signature``. También rechaza timestamps
+    viejos para evitar ataques de replay.
+
+    :raises KutiSignatureVerificationError: si la firma no coincide o el timestamp
+        está fuera de tolerancia.
+    """
+    if not signature_header.startswith(_SIGNATURE_PREFIX):
+        raise KutiSignatureVerificationError(
+            "Unexpected signature format (expected v1=<hex>)."
+        )
+
+    try:
+        timestamp_seconds = int(timestamp_header)
+    except (TypeError, ValueError) as exc:
+        raise KutiSignatureVerificationError("Invalid timestamp header.") from exc
+
+    now = int(time.time())
+    if abs(now - timestamp_seconds) > tolerance_seconds:
+        raise KutiSignatureVerificationError(
+            "Timestamp outside of tolerance — possible replay attack, "
+            "or your clock is out of sync."
+        )
+
+    body = payload if isinstance(payload, str) else payload.decode("utf-8")
+    expected = _compute_signature(secret, timestamp_seconds, body)
+    received = signature_header[len(_SIGNATURE_PREFIX) :]
+
+    if not hmac.compare_digest(expected, received):
+        raise KutiSignatureVerificationError("Signature mismatch.")
+
+
+def _compute_signature(secret: str, timestamp_seconds: int, body: str) -> str:
+    signed = f"{timestamp_seconds}.{body}".encode("utf-8")
+    return hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()

kuti_pe-1.0.0/tests/test_client.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import io
+import json
+from typing import Any, Optional
+from unittest.mock import patch
+from urllib.error import HTTPError
+
+import pytest
+
+from kuti import (
+    KutiAuthenticationError,
+    KutiClient,
+    KutiNotFoundError,
+    KutiRateLimitError,
+    KutiValidationError,
+)
+
+SECRET_KEY = "kuti_test_abc123"
+
+
+class FakeHTTPResponse:
+    def __init__(self, body: Any) -> None:
+        self._raw = json.dumps(body).encode("utf-8")
+
+    def read(self) -> bytes:
+        return self._raw
+
+    def __enter__(self) -> "FakeHTTPResponse":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        return None
+
+
+def http_error(code: int, body: Any, reason: str = "error") -> HTTPError:
+    raw = json.dumps(body).encode("utf-8")
+    return HTTPError("https://example.test/", code, reason, hdrs=None, fp=io.BytesIO(raw))  # type: ignore[arg-type]
+
+
+def error_envelope(code: str, message: str) -> dict:
+    return {
+        "success": False,
+        "message": message,
+        "error": {"code": code, "message": message, "request_id": "req_test_1"},
+    }
+
+
+def test_rejects_publishable_key() -> None:
+    with pytest.raises(ValueError, match="secret key"):
+        KutiClient("kuti_pub_test_abc")
+
+
+def test_sends_bearer_token() -> None:
+    captured: dict = {}
+
+    def fake_urlopen(req: Any, timeout: Optional[float] = None) -> FakeHTTPResponse:
+        captured["url"] = req.full_url
+        captured["headers"] = {k: v for k, v in req.header_items()}
+        return FakeHTTPResponse(
+            {
+                "data": {
+                    "id": "pi_1",
+                    "merchant_id": "mer_1",
+                    "amount": {"amount": "10.00", "currency": "PEN"},
+                    "status": "PENDING",
+                    "created_at": "2026-01-01T00:00:00Z",
+                }
+            },
+        )
+
+    with patch("kuti.client.urllib.request.urlopen", side_effect=fake_urlopen):
+        client = KutiClient(SECRET_KEY, base_url="https://example.test/v1")
+        client.payment_intents.retrieve("pi_1")
+
+    assert captured["url"] == "https://example.test/v1/payment-intents/pi_1"
+    assert captured["headers"]["Authorization"] == f"Bearer {SECRET_KEY}"
+
+
+def test_maps_nested_customer_id() -> None:
+    def fake_urlopen(req: Any, timeout: Optional[float] = None) -> FakeHTTPResponse:
+        return FakeHTTPResponse(
+            {
+                "data": {
+                    "id": "pi_1",
+                    "merchant_id": "mer_1",
+                    "customer": {
+                        "id": "cus_01ABC",
+                        "type": "INDIVIDUAL",
+                        "name": "María López",
+                    },
+                    "amount": {"amount": "50.00", "currency": "PEN"},
+                    "status": "SUCCEEDED",
+                    "paid_with": {
+                        "method_type": "INTEROPERABLE_QR",
+                        "paid_at": "2026-01-01T00:01:00Z",
+                    },
+                    "created_at": "2026-01-01T00:00:00Z",
+                }
+            },
+        )
+
+    with patch("kuti.client.urllib.request.urlopen", side_effect=fake_urlopen):
+        intent = KutiClient(SECRET_KEY).payment_intents.retrieve("pi_1")
+
+    assert intent.customer_id == "cus_01ABC"
+    assert intent.paid_with is not None
+    assert intent.paid_with.method_type == "INTEROPERABLE_QR"
+
+
+def test_maps_401() -> None:
+    with patch(
+        "kuti.client.urllib.request.urlopen",
+        side_effect=http_error(401, error_envelope("INVALID_API_KEY", "Invalid")),
+    ):
+        with pytest.raises(KutiAuthenticationError):
+            KutiClient(SECRET_KEY).payment_intents.retrieve("pi_1")
+
+
+def test_maps_404_with_code() -> None:
+    with patch(
+        "kuti.client.urllib.request.urlopen",
+        side_effect=http_error(
+            404, error_envelope("PAYMENT_INTENT_NOT_FOUND", "Not found")
+        ),
+    ):
+        with pytest.raises(KutiNotFoundError) as exc:
+            KutiClient(SECRET_KEY).payment_intents.retrieve("pi_missing")
+    assert exc.value.code == "PAYMENT_INTENT_NOT_FOUND"
+    assert exc.value.request_id == "req_test_1"
+
+
+def test_maps_422() -> None:
+    with patch(
+        "kuti.client.urllib.request.urlopen",
+        side_effect=http_error(
+            422, error_envelope("VALIDATION_ERROR", "amount is required")
+        ),
+    ):
+        with pytest.raises(KutiValidationError):
+            KutiClient(SECRET_KEY).checkout_sessions.create(
+                amount={"amount": "", "currency": "PEN"},
+                payment_method_types=[],
+            )
+
+
+def test_retries_get_on_429() -> None:
+    calls = {"n": 0}
+
+    def fake_urlopen(req: Any, timeout: Optional[float] = None):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise http_error(429, error_envelope("RATE_LIMITED", "Too many"))
+        return FakeHTTPResponse(
+            {
+                "data": {
+                    "id": "pi_1",
+                    "merchant_id": "mer_1",
+                    "amount": {"amount": "10.00", "currency": "PEN"},
+                    "status": "PENDING",
+                    "created_at": "2026-01-01T00:00:00Z",
+                }
+            },
+        )
+
+    with patch("kuti.client.time.sleep"):
+        with patch("kuti.client.urllib.request.urlopen", side_effect=fake_urlopen):
+            intent = KutiClient(SECRET_KEY).payment_intents.retrieve("pi_1")
+
+    assert intent.id == "pi_1"
+    assert calls["n"] == 2
+
+
+def test_does_not_retry_post_without_idempotency() -> None:
+    calls = {"n": 0}
+
+    def fake_urlopen(req: Any, timeout: Optional[float] = None):
+        calls["n"] += 1
+        raise http_error(429, error_envelope("RATE_LIMITED", "Too many"))
+
+    with patch("kuti.client.urllib.request.urlopen", side_effect=fake_urlopen):
+        with pytest.raises(KutiRateLimitError):
+            KutiClient(SECRET_KEY).checkout_sessions.create(
+                amount={"amount": "10.00", "currency": "PEN"},
+                payment_method_types=["INTEROPERABLE_QR"],
+            )
+    assert calls["n"] == 1
+
+
+def test_retries_post_with_idempotency_key() -> None:
+    calls = {"n": 0}
+    captured_headers: dict = {}
+
+    def fake_urlopen(req: Any, timeout: Optional[float] = None):
+        calls["n"] += 1
+        captured_headers.update({k: v for k, v in req.header_items()})
+        if calls["n"] == 1:
+            raise http_error(429, error_envelope("RATE_LIMITED", "Too many"))
+        return FakeHTTPResponse(
+            {
+                "data": {
+                    "id": "cs_1",
+                    "merchant_id": "mer_1",
+                    "payment_intent_id": "pi_1",
+                    "amount": {"amount": "10.00", "currency": "PEN"},
+                    "status": "OPEN",
+                    "created_at": "2026-01-01T00:00:00Z",
+                }
+            },
+        )
+
+    with patch("kuti.client.time.sleep"):
+        with patch("kuti.client.urllib.request.urlopen", side_effect=fake_urlopen):
+            session = KutiClient(SECRET_KEY).checkout_sessions.create(
+                amount={"amount": "10.00", "currency": "PEN"},
+                payment_method_types=["INTEROPERABLE_QR"],
+                idempotency_key="order-42",
+            )
+
+    assert session.id == "cs_1"
+    assert calls["n"] == 2
+    headers_lower = {k.lower(): v for k, v in captured_headers.items()}
+    assert headers_lower.get("idempotency-key") == "order-42"

kuti_pe-1.0.0/tests/test_webhooks.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+import pytest
+
+from kuti import KutiSignatureVerificationError, verify_webhook_signature
+
+SECRET = "whsec_test_1234567890"
+
+
+def sign(secret: str, timestamp_seconds: int, body: str) -> str:
+    digest = hmac.new(
+        secret.encode(),
+        f"{timestamp_seconds}.{body}".encode(),
+        hashlib.sha256,
+    ).hexdigest()
+    return f"v1={digest}"
+
+
+def test_accepts_valid_signature() -> None:
+    body = '{"type":"payment.succeeded","id":"evt_1"}'
+    now = int(time.time())
+    verify_webhook_signature(body, sign(SECRET, now, body), str(now), SECRET)
+
+
+def test_rejects_wrong_secret() -> None:
+    body = "{}"
+    now = int(time.time())
+    with pytest.raises(KutiSignatureVerificationError):
+        verify_webhook_signature(body, sign("wrong", now, body), str(now), SECRET)
+
+
+def test_rejects_tampered_body() -> None:
+    now = int(time.time())
+    signature = sign(SECRET, now, '{"amount":"10.00"}')
+    with pytest.raises(KutiSignatureVerificationError):
+        verify_webhook_signature('{"amount":"999.00"}', signature, str(now), SECRET)
+
+
+def test_rejects_stale_timestamp() -> None:
+    body = "{}"
+    stale = int(time.time()) - 3600
+    with pytest.raises(KutiSignatureVerificationError):
+        verify_webhook_signature(body, sign(SECRET, stale, body), str(stale), SECRET)
+
+
+def test_accepts_stale_with_wide_tolerance() -> None:
+    body = "{}"
+    stale = int(time.time()) - 3600
+    verify_webhook_signature(
+        body, sign(SECRET, stale, body), str(stale), SECRET, tolerance_seconds=7200
+    )
+
+
+def test_rejects_malformed_header() -> None:
+    with pytest.raises(KutiSignatureVerificationError):
+        verify_webhook_signature(
+            "{}", "not-a-valid-signature", str(int(time.time())), SECRET
+        )