nxgate-sdk-python 1.0.0__py3-none-any.whl

nxgate/__init__.py

@@ -0,0 +1,59 @@
+"""NXGATE PIX SDK for Python.
+
+Usage::
+
+    from nxgate import NXGate, NXGateWebhook
+
+    nx = NXGate(client_id="...", client_secret="...")
+    charge = nx.pix_generate(
+        valor=100.00,
+        nome_pagador="Joao da Silva",
+        documento_pagador="12345678901",
+    )
+"""
+
+from .client import NXGate
+from .errors import (
+    NXGateAuthError,
+    NXGateError,
+    NXGateRetryError,
+    NXGateTimeoutError,
+)
+from .types import (
+    BalanceResponse,
+    CashInEvent,
+    CashInEventData,
+    CashOutEvent,
+    PixGenerateResponse,
+    PixWithdrawResponse,
+    SplitUser,
+    TokenResponse,
+    TransactionResponse,
+    WebhookEvent,
+)
+from .webhook import NXGateWebhook
+
+__all__ = [
+    # Client
+    "NXGate",
+    # Webhook
+    "NXGateWebhook",
+    # Errors
+    "NXGateError",
+    "NXGateAuthError",
+    "NXGateRetryError",
+    "NXGateTimeoutError",
+    # Types
+    "BalanceResponse",
+    "CashInEvent",
+    "CashInEventData",
+    "CashOutEvent",
+    "PixGenerateResponse",
+    "PixWithdrawResponse",
+    "SplitUser",
+    "TokenResponse",
+    "TransactionResponse",
+    "WebhookEvent",
+]
+
+__version__ = "1.0.0"

nxgate/auth.py

@@ -0,0 +1,105 @@
+"""Token management for the NXGATE SDK."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import TYPE_CHECKING
+
+from .errors import NXGateAuthError
+from .types import TokenResponse
+
+if TYPE_CHECKING:
+    pass
+
+_TOKEN_MARGIN_SECONDS = 60  # refresh token 60 s before it expires
+
+
+class TokenManager:
+    """Fetches and caches OAuth2 Bearer tokens.
+
+    The token is automatically refreshed when it is about to expire (with a
+    60-second safety margin).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        client_id: str,
+        client_secret: str,
+        *,
+        timeout: int = 30,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._timeout = timeout
+
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    # ── public API ────────────────────────────────────────────────────────
+
+    def get_token(self) -> str:
+        """Return a valid access token, refreshing when needed."""
+        if self._token is None or time.time() >= self._expires_at:
+            self._refresh()
+        assert self._token is not None
+        return self._token
+
+    def invalidate(self) -> None:
+        """Force the next call to ``get_token`` to fetch a new token."""
+        self._token = None
+        self._expires_at = 0.0
+
+    # ── internals ─────────────────────────────────────────────────────────
+
+    def _refresh(self) -> None:
+        url = f"{self._base_url}/oauth2/token"
+        payload = json.dumps(
+            {
+                "grant_type": "client_credentials",
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+            }
+        ).encode("utf-8")
+
+        req = urllib.request.Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                body = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            try:
+                detail = json.loads(exc.read().decode("utf-8"))
+            except Exception:
+                detail = {}
+            err = detail.get("error", {})
+            if isinstance(err, str):
+                msg = err
+            else:
+                msg = err.get("description", str(exc))
+            raise NXGateAuthError(
+                f"Failed to obtain token: {msg}",
+                status_code=exc.code,
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise NXGateAuthError(
+                f"Failed to connect to {url}: {exc.reason}"
+            ) from exc
+
+        token_resp = TokenResponse(
+            access_token=body["access_token"],
+            token_type=body.get("token_type", "Bearer"),
+            expires_in=int(body.get("expires_in", 3600)),
+        )
+
+        self._token = token_resp.access_token
+        self._expires_at = time.time() + token_resp.expires_in - _TOKEN_MARGIN_SECONDS

nxgate/client.py

@@ -0,0 +1,251 @@
+"""Main client for the NXGATE PIX SDK."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .auth import TokenManager
+from .errors import NXGateError, NXGateRetryError, NXGateTimeoutError
+from .hmac_signer import HmacSigner
+from .types import (
+    BalanceResponse,
+    PixGenerateRequest,
+    PixGenerateResponse,
+    PixWithdrawRequest,
+    PixWithdrawResponse,
+    SplitUser,
+    TransactionResponse,
+)
+
+_DEFAULT_BASE_URL = "https://api.nxgate.com.br"
+_DEFAULT_TIMEOUT = 30
+_MAX_RETRIES = 2
+_RETRY_BASE_DELAY = 1.0  # seconds
+
+
+class NXGate:
+    """Synchronous client for the NXGATE PIX API.
+
+    Parameters:
+        client_id: Your NXGATE ``client_id``.
+        client_secret: Your NXGATE ``client_secret``.
+        hmac_secret: Optional HMAC secret.  When provided every request is
+            automatically signed with HMAC-SHA256 headers.
+        base_url: API base URL (defaults to ``https://api.nxgate.com.br``).
+        timeout: HTTP request timeout in seconds (default ``30``).
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        hmac_secret: str | None = None,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._client_id = client_id
+
+        self._token_manager = TokenManager(
+            base_url=self._base_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            timeout=timeout,
+        )
+
+        self._signer: HmacSigner | None = None
+        if hmac_secret:
+            self._signer = HmacSigner(client_id, hmac_secret)
+
+    # ── Public API ────────────────────────────────────────────────────────
+
+    def pix_generate(
+        self,
+        valor: float,
+        nome_pagador: str,
+        documento_pagador: str,
+        *,
+        forcar_pagador: bool | None = None,
+        email_pagador: str | None = None,
+        celular: str | None = None,
+        descricao: str | None = None,
+        webhook: str | None = None,
+        magic_id: str | None = None,
+        api_key: str | None = None,
+        split_users: list[dict[str, Any]] | None = None,
+    ) -> PixGenerateResponse:
+        """Generate a PIX charge (cash-in) and return a QR Code.
+
+        Returns:
+            :class:`PixGenerateResponse` with payment code and transaction id.
+        """
+        parsed_splits: list[SplitUser] | None = None
+        if split_users is not None:
+            parsed_splits = [
+                SplitUser(username=s["username"], percentage=s["percentage"])
+                for s in split_users
+            ]
+
+        req = PixGenerateRequest(
+            valor=valor,
+            nome_pagador=nome_pagador,
+            documento_pagador=documento_pagador,
+            forcar_pagador=forcar_pagador,
+            email_pagador=email_pagador,
+            celular=celular,
+            descricao=descricao,
+            webhook=webhook,
+            magic_id=magic_id,
+            api_key=api_key,
+            split_users=parsed_splits,
+        )
+
+        data = self._request("POST", "/pix/gerar", body=req.to_dict())
+        return PixGenerateResponse.from_dict(data)
+
+    def pix_withdraw(
+        self,
+        valor: float,
+        chave_pix: str,
+        tipo_chave: str,
+        *,
+        documento: str | None = None,
+        webhook: str | None = None,
+        magic_id: str | None = None,
+        api_key: str | None = None,
+    ) -> PixWithdrawResponse:
+        """Execute a PIX withdrawal (cash-out).
+
+        Returns:
+            :class:`PixWithdrawResponse` with status and internal reference.
+        """
+        req = PixWithdrawRequest(
+            valor=valor,
+            chave_pix=chave_pix,
+            tipo_chave=tipo_chave,
+            documento=documento,
+            webhook=webhook,
+            magic_id=magic_id,
+            api_key=api_key,
+        )
+
+        data = self._request("POST", "/pix/sacar", body=req.to_dict())
+        return PixWithdrawResponse.from_dict(data)
+
+    def get_balance(self) -> BalanceResponse:
+        """Check current account balance.
+
+        Returns:
+            :class:`BalanceResponse` with balance, blocked and available.
+        """
+        data = self._request("GET", "/v1/balance")
+        return BalanceResponse.from_dict(data)
+
+    def get_transaction(
+        self,
+        type: str,
+        txid: str,
+    ) -> TransactionResponse:
+        """Retrieve a specific transaction.
+
+        Parameters:
+            type: ``"cash-in"`` or ``"cash-out"``.
+            txid: The transaction identifier.
+
+        Returns:
+            :class:`TransactionResponse` with transaction details.
+        """
+        params = urllib.parse.urlencode({"type": type, "txid": txid})
+        data = self._request("GET", f"/v1/transactions?{params}")
+        return TransactionResponse.from_dict(data)
+
+    # ── Internals ─────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict | None = None,
+    ) -> dict:
+        """Execute an authenticated HTTP request with retry on 503."""
+        token = self._token_manager.get_token()
+
+        body_bytes: bytes | None = None
+        body_str = ""
+        if body is not None:
+            body_str = json.dumps(body)
+            body_bytes = body_str.encode("utf-8")
+
+        # Resolve full URL - path may already contain query params
+        url = f"{self._base_url}{path}"
+
+        last_exc: Exception | None = None
+        for attempt in range(_MAX_RETRIES + 1):
+            headers: dict[str, str] = {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+
+            if self._signer is not None:
+                # Sign using only the path portion (before query string)
+                sign_path = path.split("?")[0]
+                hmac_headers = self._signer.sign(method, sign_path, body_str)
+                headers.update(hmac_headers)
+
+            req = urllib.request.Request(
+                url,
+                data=body_bytes,
+                headers=headers,
+                method=method,
+            )
+
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                    return json.loads(resp.read().decode("utf-8"))
+            except urllib.error.HTTPError as exc:
+                if exc.code == 503 and attempt < _MAX_RETRIES:
+                    last_exc = exc
+                    time.sleep(_RETRY_BASE_DELAY * (2 ** attempt))
+                    continue
+
+                # Try to parse structured error
+                try:
+                    detail = json.loads(exc.read().decode("utf-8"))
+                except Exception:
+                    detail = {}
+
+                err = detail.get("error", {})
+                if isinstance(err, str):
+                    raise NXGateError(
+                        err,
+                        status_code=exc.code,
+                    ) from exc
+                raise NXGateError(
+                    err.get("description", str(exc)),
+                    title=err.get("title"),
+                    code=err.get("code"),
+                    description=err.get("description"),
+                    status_code=exc.code,
+                ) from exc
+            except urllib.error.URLError as exc:
+                if "timed out" in str(exc.reason):
+                    raise NXGateTimeoutError(
+                        f"Request timed out after {self._timeout}s"
+                    ) from exc
+                raise NXGateError(
+                    f"Connection error: {exc.reason}"
+                ) from exc
+
+        raise NXGateRetryError(
+            f"All {_MAX_RETRIES + 1} attempts failed for {method} {path}",
+            status_code=503,
+        )

nxgate/errors.py

@@ -0,0 +1,50 @@
+"""Exceptions for the NXGATE SDK."""
+
+from __future__ import annotations
+
+
+class NXGateError(Exception):
+    """Base exception for all NXGATE SDK errors.
+
+    Attributes:
+        title: Short error title (e.g. ``"Unauthorized"``).
+        code: Machine-readable error code returned by the API.
+        description: Human-readable explanation of the error.
+        status_code: HTTP status code, when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        title: str | None = None,
+        code: str | None = None,
+        description: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.title = title
+        self.code = code
+        self.description = description
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        parts = [f"NXGateError({str(self)!r}"]
+        if self.status_code is not None:
+            parts.append(f", status_code={self.status_code}")
+        if self.code is not None:
+            parts.append(f", code={self.code!r}")
+        parts.append(")")
+        return "".join(parts)
+
+
+class NXGateAuthError(NXGateError):
+    """Raised when authentication / token retrieval fails."""
+
+
+class NXGateTimeoutError(NXGateError):
+    """Raised when a request exceeds the configured timeout."""
+
+
+class NXGateRetryError(NXGateError):
+    """Raised when all retry attempts have been exhausted."""

nxgate/hmac_signer.py

@@ -0,0 +1,56 @@
+"""HMAC request signing for the NXGATE SDK."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import uuid
+from datetime import datetime, timezone
+
+
+class HmacSigner:
+    """Generates HMAC-SHA256 headers for API request authentication.
+
+    The signature is computed over the canonical string::
+
+        METHOD\\nPATH\\nTIMESTAMP\\nNONCE\\nBODY
+    """
+
+    def __init__(self, client_id: str, hmac_secret: str) -> None:
+        self._client_id = client_id
+        self._secret = hmac_secret.encode("utf-8")
+
+    def sign(
+        self,
+        method: str,
+        path: str,
+        body: str = "",
+    ) -> dict[str, str]:
+        """Return the HMAC headers for a single request.
+
+        Parameters:
+            method: HTTP method (e.g. ``"POST"``).
+            path: Request path (e.g. ``"/pix/gerar"``).
+            body: Serialised request body (empty string for GET).
+
+        Returns:
+            A dict with the four required headers.
+        """
+        timestamp = datetime.now(timezone.utc).isoformat()
+        nonce = uuid.uuid4().hex
+
+        canonical = f"{method}\n{path}\n{timestamp}\n{nonce}\n{body}"
+        signature = hmac.new(
+            self._secret,
+            canonical.encode("utf-8"),
+            hashlib.sha256,
+        ).digest()
+        signature_b64 = base64.b64encode(signature).decode("ascii")
+
+        return {
+            "X-Client-ID": self._client_id,
+            "X-HMAC-Signature": signature_b64,
+            "X-HMAC-Timestamp": timestamp,
+            "X-HMAC-Nonce": nonce,
+        }

nxgate/types.py

@@ -0,0 +1,297 @@
+"""Data classes for the NXGATE SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+# ── Auth ──────────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class TokenResponse:
+    """Represents the response from ``POST /oauth2/token``."""
+
+    access_token: str
+    token_type: str
+    expires_in: int
+
+
+# ── PIX Cash-in ───────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class SplitUser:
+    """Describes a split payment participant."""
+
+    username: str
+    percentage: float
+
+
+@dataclass
+class PixGenerateRequest:
+    """Payload for ``POST /pix/gerar``."""
+
+    valor: float
+    nome_pagador: str
+    documento_pagador: str
+    forcar_pagador: bool | None = None
+    email_pagador: str | None = None
+    celular: str | None = None
+    descricao: str | None = None
+    webhook: str | None = None
+    magic_id: str | None = None
+    api_key: str | None = None
+    split_users: list[SplitUser] | None = None
+
+    def to_dict(self) -> dict:
+        data: dict = {
+            "valor": self.valor,
+            "nome_pagador": self.nome_pagador,
+            "documento_pagador": self.documento_pagador,
+        }
+        if self.forcar_pagador is not None:
+            data["forcar_pagador"] = self.forcar_pagador
+        if self.email_pagador is not None:
+            data["email_pagador"] = self.email_pagador
+        if self.celular is not None:
+            data["celular"] = self.celular
+        if self.descricao is not None:
+            data["descricao"] = self.descricao
+        if self.webhook is not None:
+            data["webhook"] = self.webhook
+        if self.magic_id is not None:
+            data["magic_id"] = self.magic_id
+        if self.api_key is not None:
+            data["api_key"] = self.api_key
+        if self.split_users is not None:
+            data["split_users"] = [
+                {"username": s.username, "percentage": s.percentage}
+                for s in self.split_users
+            ]
+        return data
+
+
+@dataclass(frozen=True)
+class PixGenerateResponse:
+    """Response from ``POST /pix/gerar``."""
+
+    status: str
+    message: str
+    paymentCode: str
+    idTransaction: str
+    paymentCodeBase64: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> PixGenerateResponse:
+        return cls(
+            status=data.get("status", ""),
+            message=data.get("message", ""),
+            paymentCode=data.get("paymentCode", ""),
+            idTransaction=data.get("idTransaction", ""),
+            paymentCodeBase64=data.get("paymentCodeBase64", ""),
+        )
+
+
+# ── PIX Cash-out ──────────────────────────────────────────────────────────
+
+TIPO_CHAVE_VALUES = {"CPF", "CNPJ", "PHONE", "EMAIL", "RANDOM"}
+
+
+@dataclass
+class PixWithdrawRequest:
+    """Payload for ``POST /pix/sacar``."""
+
+    valor: float
+    chave_pix: str
+    tipo_chave: str  # CPF | CNPJ | PHONE | EMAIL | RANDOM
+    documento: str | None = None
+    webhook: str | None = None
+    magic_id: str | None = None
+    api_key: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.tipo_chave not in TIPO_CHAVE_VALUES:
+            raise ValueError(
+                f"tipo_chave must be one of {TIPO_CHAVE_VALUES}, "
+                f"got {self.tipo_chave!r}"
+            )
+
+    def to_dict(self) -> dict:
+        data: dict = {
+            "valor": self.valor,
+            "chave_pix": self.chave_pix,
+            "tipo_chave": self.tipo_chave,
+        }
+        if self.documento is not None:
+            data["documento"] = self.documento
+        if self.webhook is not None:
+            data["webhook"] = self.webhook
+        if self.magic_id is not None:
+            data["magic_id"] = self.magic_id
+        if self.api_key is not None:
+            data["api_key"] = self.api_key
+        return data
+
+
+@dataclass(frozen=True)
+class PixWithdrawResponse:
+    """Response from ``POST /pix/sacar``."""
+
+    status: str
+    message: str
+    internalreference: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> PixWithdrawResponse:
+        return cls(
+            status=data.get("status", ""),
+            message=data.get("message", ""),
+            internalreference=data.get("internalreference", ""),
+        )
+
+
+# ── Balance ───────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class BalanceResponse:
+    """Response from ``GET /v1/balance``."""
+
+    balance: float
+    blocked: float
+    available: float
+
+    @classmethod
+    def from_dict(cls, data: dict) -> BalanceResponse:
+        return cls(
+            balance=float(data.get("balance", 0)),
+            blocked=float(data.get("blocked", 0)),
+            available=float(data.get("available", 0)),
+        )
+
+
+# ── Transactions ──────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class TransactionResponse:
+    """Response from ``GET /v1/transactions``."""
+
+    idTransaction: str
+    status: str
+    amount: float
+    paidAt: str | None
+    endToEnd: str | None
+    raw: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TransactionResponse:
+        return cls(
+            idTransaction=data.get("idTransaction", ""),
+            status=data.get("status", ""),
+            amount=float(data.get("amount", 0)),
+            paidAt=data.get("paidAt"),
+            endToEnd=data.get("endToEnd"),
+            raw=data,
+        )
+
+
+# ── Webhook Events ───────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class CashInEventData:
+    """Payload inside a cash-in webhook event."""
+
+    amount: float
+    status: str
+    worked: bool
+    tag: str
+    tx_id: str
+    end_to_end: str
+    payment_date: str
+    debtor_name: str
+    debtor_document: str
+    type_document: str
+    magic_id: str
+    fee: float
+    raw: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> CashInEventData:
+        return cls(
+            amount=float(data.get("amount", 0)),
+            status=data.get("status", ""),
+            worked=bool(data.get("worked", False)),
+            tag=data.get("tag", ""),
+            tx_id=data.get("tx_id", ""),
+            end_to_end=data.get("end_to_end", ""),
+            payment_date=data.get("payment_date", ""),
+            debtor_name=data.get("debtor_name", ""),
+            debtor_document=data.get("debtor_document", ""),
+            type_document=data.get("type_document", ""),
+            magic_id=data.get("magic_id", ""),
+            fee=float(data.get("fee", 0)),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True)
+class CashInEvent:
+    """Cash-in webhook event."""
+
+    type: str  # QR_CODE_COPY_AND_PASTE_PAID | QR_CODE_COPY_AND_PASTE_REFUNDED
+    data: CashInEventData
+
+    @classmethod
+    def from_dict(cls, payload: dict) -> CashInEvent:
+        return cls(
+            type=payload["type"],
+            data=CashInEventData.from_dict(payload.get("data", {})),
+        )
+
+
+@dataclass(frozen=True)
+class CashOutEvent:
+    """Cash-out webhook event."""
+
+    type: str  # PIX_CASHOUT_SUCCESS | PIX_CASHOUT_ERROR | PIX_CASHOUT_REFUNDED
+    worked: bool
+    status: str
+    idTransaction: str
+    amount: float
+    key: str
+    end_to_end: str
+    payment_date: str
+    magic_id: str
+    fee: float
+    error: str | None
+    raw: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, payload: dict) -> CashOutEvent:
+        return cls(
+            type=payload["type"],
+            worked=bool(payload.get("worked", False)),
+            status=payload.get("status", ""),
+            idTransaction=payload.get("idTransaction", ""),
+            amount=float(payload.get("amount", 0)),
+            key=payload.get("key", ""),
+            end_to_end=payload.get("end_to_end", ""),
+            payment_date=payload.get("payment_date", ""),
+            magic_id=payload.get("magic_id", ""),
+            fee=float(payload.get("fee", 0)),
+            error=payload.get("error"),
+            raw=payload,
+        )
+
+
+# Union-like alias for webhook events
+WebhookEvent = CashInEvent | CashOutEvent
+
+CASHIN_TYPES = {
+    "QR_CODE_COPY_AND_PASTE_PAID",
+    "QR_CODE_COPY_AND_PASTE_REFUNDED",
+}
+
+CASHOUT_TYPES = {
+    "PIX_CASHOUT_SUCCESS",
+    "PIX_CASHOUT_ERROR",
+    "PIX_CASHOUT_REFUNDED",
+}

nxgate/webhook.py

@@ -0,0 +1,48 @@
+"""Webhook event parser for the NXGATE SDK."""
+
+from __future__ import annotations
+
+from .errors import NXGateError
+from .types import (
+    CASHIN_TYPES,
+    CASHOUT_TYPES,
+    CashInEvent,
+    CashOutEvent,
+    WebhookEvent,
+)
+
+
+class NXGateWebhook:
+    """Stateless helper to parse incoming webhook payloads."""
+
+    @staticmethod
+    def parse(payload: dict) -> WebhookEvent:
+        """Parse a raw webhook JSON payload into a typed event.
+
+        Parameters:
+            payload: The decoded JSON body sent by NXGATE to your webhook
+                endpoint.
+
+        Returns:
+            A :class:`CashInEvent` or :class:`CashOutEvent`.
+
+        Raises:
+            NXGateError: If the ``type`` field is missing or unrecognised.
+        """
+        event_type = payload.get("type")
+        if not event_type:
+            raise NXGateError(
+                "Webhook payload is missing the 'type' field.",
+                code="INVALID_WEBHOOK",
+            )
+
+        if event_type in CASHIN_TYPES:
+            return CashInEvent.from_dict(payload)
+
+        if event_type in CASHOUT_TYPES:
+            return CashOutEvent.from_dict(payload)
+
+        raise NXGateError(
+            f"Unknown webhook event type: {event_type!r}",
+            code="UNKNOWN_WEBHOOK_TYPE",
+        )

nxgate_sdk_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: nxgate-sdk-python
+Version: 1.0.0
+Summary: SDK oficial da NXGATE para integração com a API PIX
+Author-email: NXGATE <suporte@nxgate.com.br>
+License: MIT
+Project-URL: Homepage, https://github.com/nxgate/nxgate-sdk-python
+Project-URL: Documentation, https://github.com/nxgate/nxgate-sdk-python#readme
+Project-URL: Repository, https://github.com/nxgate/nxgate-sdk-python
+Keywords: nxgate,pix,pagamentos,qrcode,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# NXGATE PIX SDK para Python
+
+SDK oficial da NXGATE para integração com a API PIX. Permite gerar cobranças (cash-in), realizar saques (cash-out), consultar saldo e transações, tudo com tipagem completa e zero dependências externas.
+
+## Requisitos
+
+- Python 3.10 ou superior
+- Sem dependências externas (usa apenas a biblioteca padrão)
+
+## Instalação
+
+```bash
+pip install nxgate
+```
+
+Ou instale diretamente do repositório:
+
+```bash
+pip install git+https://github.com/nxgate/sdk-python.git
+```
+
+## Início Rápido
+
+```python
+from nxgate import NXGate, NXGateWebhook
+
+nx = NXGate(
+    client_id="nxgate_xxx",
+    client_secret="secret",
+    hmac_secret="opcional",  # opcional - quando informado, todas as requisições são assinadas com HMAC-SHA256
+)
+```
+
+## Funcionalidades
+
+### Gerar cobrança PIX (Cash-in)
+
+Gera uma cobrança PIX e retorna o QR Code para pagamento.
+
+```python
+charge = nx.pix_generate(
+    valor=100.00,
+    nome_pagador="João da Silva",
+    documento_pagador="12345678901",
+    webhook="https://meusite.com/webhook",
+    descricao="Pedido #1234",
+    email_pagador="joao@email.com",
+    celular="11999999999",
+)
+
+print(charge.status)            # "ACTIVE"
+print(charge.paymentCode)       # código copia-e-cola
+print(charge.idTransaction)     # ID da transação
+print(charge.paymentCodeBase64) # QR Code em base64
+```
+
+#### Cobrança com split de pagamento
+
+```python
+charge = nx.pix_generate(
+    valor=200.00,
+    nome_pagador="Maria Souza",
+    documento_pagador="98765432100",
+    split_users=[
+        {"username": "loja_a", "percentage": 70.0},
+        {"username": "loja_b", "percentage": 30.0},
+    ],
+)
+```
+
+### Saque PIX (Cash-out)
+
+Realiza uma transferência PIX para uma chave destino.
+
+```python
+withdrawal = nx.pix_withdraw(
+    valor=50.00,
+    chave_pix="joao@email.com",
+    tipo_chave="EMAIL",  # CPF | CNPJ | PHONE | EMAIL | RANDOM
+    webhook="https://meusite.com/webhook",
+)
+
+print(withdrawal.status)            # "PROCESSING"
+print(withdrawal.internalreference) # referência interna
+```
+
+### Consultar saldo
+
+```python
+balance = nx.get_balance()
+
+print(balance.balance)   # saldo total
+print(balance.blocked)   # saldo bloqueado
+print(balance.available) # saldo disponível
+```
+
+### Consultar transação
+
+```python
+tx = nx.get_transaction(type="cash-in", txid="px_xxx")
+
+print(tx.idTransaction) # ID da transação
+print(tx.status)        # status atual
+print(tx.amount)        # valor
+print(tx.paidAt)        # data do pagamento
+print(tx.endToEnd)      # identificador end-to-end
+```
+
+## Webhooks
+
+O SDK fornece um parser para eventos recebidos via webhook.
+
+### Recebendo eventos (exemplo com Flask)
+
+```python
+from flask import Flask, request, jsonify
+from nxgate import NXGateWebhook, NXGateError
+from nxgate.types import CashInEvent, CashOutEvent
+
+app = Flask(__name__)
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    try:
+        event = NXGateWebhook.parse(request.json)
+    except NXGateError as e:
+        return jsonify({"error": str(e)}), 400
+
+    if isinstance(event, CashInEvent):
+        print(f"Cash-in: {event.type}")
+        print(f"  Valor: R$ {event.data.amount:.2f}")
+        print(f"  Pagador: {event.data.debtor_name}")
+        print(f"  TX ID: {event.data.tx_id}")
+        print(f"  Status: {event.data.status}")
+
+    elif isinstance(event, CashOutEvent):
+        print(f"Cash-out: {event.type}")
+        print(f"  Valor: R$ {event.amount:.2f}")
+        print(f"  Chave: {event.key}")
+        if event.error:
+            print(f"  Erro: {event.error}")
+
+    return jsonify({"ok": True})
+```
+
+### Tipos de evento
+
+**Cash-in:**
+- `QR_CODE_COPY_AND_PASTE_PAID` - pagamento confirmado
+- `QR_CODE_COPY_AND_PASTE_REFUNDED` - pagamento devolvido
+
+**Cash-out:**
+- `PIX_CASHOUT_SUCCESS` - saque realizado com sucesso
+- `PIX_CASHOUT_ERROR` - erro no saque
+- `PIX_CASHOUT_REFUNDED` - saque devolvido
+
+## Assinatura HMAC
+
+Quando o parâmetro `hmac_secret` é informado na inicialização do cliente, todas as requisições são automaticamente assinadas com HMAC-SHA256. Os seguintes headers são adicionados:
+
+| Header | Descrição |
+|--------|-----------|
+| `X-Client-ID` | Seu `client_id` |
+| `X-HMAC-Signature` | Assinatura HMAC-SHA256 em base64 |
+| `X-HMAC-Timestamp` | Timestamp ISO 8601 |
+| `X-HMAC-Nonce` | Valor único por requisição |
+
+A assinatura é gerada sobre a string canônica:
+
+```
+METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY
+```
+
+## Gerenciamento de Token
+
+O SDK gerencia automaticamente o token OAuth2:
+
+- O token é obtido na primeira requisição
+- É mantido em cache enquanto válido
+- É renovado automaticamente 60 segundos antes de expirar
+- Em caso de falha na autenticação, `NXGateAuthError` é lançado
+
+## Tratamento de Erros
+
+```python
+from nxgate import NXGate, NXGateError
+from nxgate.errors import NXGateAuthError, NXGateTimeoutError, NXGateRetryError
+
+nx = NXGate(client_id="xxx", client_secret="yyy")
+
+try:
+    charge = nx.pix_generate(
+        valor=100.00,
+        nome_pagador="Teste",
+        documento_pagador="00000000000",
+    )
+except NXGateAuthError as e:
+    print(f"Erro de autenticação: {e}")
+    print(f"Status HTTP: {e.status_code}")
+except NXGateTimeoutError as e:
+    print(f"Timeout: {e}")
+except NXGateRetryError as e:
+    print(f"Todas as tentativas falharam: {e}")
+except NXGateError as e:
+    print(f"Erro da API: {e}")
+    print(f"Título: {e.title}")
+    print(f"Código: {e.code}")
+    print(f"Descrição: {e.description}")
+    print(f"Status HTTP: {e.status_code}")
+```
+
+### Hierarquia de exceções
+
+```
+Exception
+└── NXGateError
+    ├── NXGateAuthError      # falha na autenticação
+    ├── NXGateTimeoutError   # timeout na requisição
+    └── NXGateRetryError     # tentativas esgotadas (503)
+```
+
+## Retry Automático
+
+Requisições que retornam HTTP 503 são automaticamente retentadas com backoff exponencial:
+
+- Máximo de 2 retentativas (3 tentativas no total)
+- Delay entre tentativas: 1s, 2s
+- Se todas as tentativas falharem, `NXGateRetryError` é lançado
+
+## Referência da API
+
+### `NXGate(client_id, client_secret, hmac_secret=None, *, base_url, timeout)`
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|-----------|------|-------------|-----------|
+| `client_id` | `str` | Sim | Seu client_id NXGATE |
+| `client_secret` | `str` | Sim | Seu client_secret NXGATE |
+| `hmac_secret` | `str \| None` | Não | Secret para assinatura HMAC |
+| `base_url` | `str` | Não | URL base da API (padrão: `https://api.nxgate.com.br`) |
+| `timeout` | `int` | Não | Timeout em segundos (padrão: `30`) |
+
+### Métodos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `pix_generate(...)` | `PixGenerateResponse` | Gera cobrança PIX |
+| `pix_withdraw(...)` | `PixWithdrawResponse` | Realiza saque PIX |
+| `get_balance()` | `BalanceResponse` | Consulta saldo |
+| `get_transaction(type, txid)` | `TransactionResponse` | Consulta transação |
+
+## Desenvolvimento
+
+### Executar testes
+
+```bash
+pip install pytest
+pytest
+```
+
+### Estrutura do projeto
+
+```
+nxgate/
+├── __init__.py      # exports públicos
+├── client.py        # classe NXGate
+├── auth.py          # gerenciamento de token
+├── hmac_signer.py   # assinatura HMAC
+├── webhook.py       # parser de webhook
+├── errors.py        # exceções
+└── types.py         # dataclasses tipadas
+```
+
+## Licença
+
+MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.

nxgate_sdk_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+nxgate/__init__.py,sha256=RXcUkCzrlJyS0iIh_YjbsVtyX7VI2VEB5FuJseUJjrY,1120
+nxgate/auth.py,sha256=EsND1FEl1jemmWNuIZLL1yhmJAdEpKHV3TBcvgRQ7_o,3406
+nxgate/client.py,sha256=Cl-pJibhAOi06TweebsvqZbKXM3caiDATPfiCzSD5tQ,8259
+nxgate/errors.py,sha256=ae5m9N7meE2voTafcEqc6rhVb9sc-5yP14YvVPWGMFY,1439
+nxgate/hmac_signer.py,sha256=kYcY977WnqC2gn1GEnbVXNQ0KswGSE_nA0ijjciJybQ,1557
+nxgate/types.py,sha256=sMl1pZU5lnIOpmdSSvUjyFNZsnENnFcXUHEnGEuRrrY,9059
+nxgate/webhook.py,sha256=hT_UtJ8WDToimqYiB9kPHuR2w93ltEfg-rf45cY2Y3s,1285
+nxgate_sdk_python-1.0.0.dist-info/licenses/LICENSE,sha256=rzvC6KhelMbCpKgYRDIbrqN8m4J6XwiWHNih4NTFf7U,1063
+nxgate_sdk_python-1.0.0.dist-info/METADATA,sha256=JbiQ-u2JqzsgrfkdIMAlhf-g_w968ecm9pO0_USFBSQ,8555
+nxgate_sdk_python-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nxgate_sdk_python-1.0.0.dist-info/top_level.txt,sha256=Kem3KARfoXYGgH_omjOBK8axGMfqIhj8DgIe5NGeGVQ,7
+nxgate_sdk_python-1.0.0.dist-info/RECORD,,

nxgate_sdk_python-1.0.0.dist-info/WHEEL

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

nxgate_sdk_python-1.0.0.dist-info/licenses/LICENSE

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

nxgate_sdk_python-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nxgate