pysibs 0.1.0__tar.gz

pysibs-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Secrets / local config
+.env
+.env.*
+!.env.example
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

pysibs-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/) and the format is based on
+[Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-19
+
+### Added
+- Initial `SIBSClient` (synchronous) and `AsyncSIBSClient` (asynchronous).
+- `create_payment`, `get_payment_status`, `refund_payment`, `capture_payment` and
+  `cancel_payment`.
+- `from_env()` constructor reading `SIBS_*` environment variables.
+- Typed Pydantic models with normalized `PaymentStatus` and preserved `raw_response`.
+- `Decimal`-based money handling that rejects `float`.
+- Webhook parsing (`parse_webhook`) and configurable signature verification
+  (`verify_webhook_signature`, `hmac_sha256_verifier`).
+- Full exception hierarchy under `SIBSError`; raw `httpx` errors never leak.
+- Documentation, examples (Django/FastAPI), CI and PyPI publish workflows.
+
+[Unreleased]: https://github.com/robertruben98/pysibs/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/robertruben98/pysibs/releases/tag/v0.1.0

pysibs-0.1.0/LICENSE

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

pysibs-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: pysibs
+Version: 0.1.0
+Summary: A modern Python SDK for SIBS Gateway payment integrations.
+Project-URL: Homepage, https://github.com/robertruben98/pysibs
+Project-URL: Repository, https://github.com/robertruben98/pysibs
+Project-URL: Issues, https://github.com/robertruben98/pysibs/issues
+Project-URL: Documentation, https://github.com/robertruben98/pysibs#readme
+Author: Robert Benitez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fintech,mbway,multibanco,payment-gateway,payments,python-sdk,sibs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: django; extra == 'examples'
+Requires-Dist: fastapi; extra == 'examples'
+Requires-Dist: python-dotenv; extra == 'examples'
+Requires-Dist: uvicorn; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# PySIBS
+
+A modern, typed, developer-friendly Python SDK for [SIBS Gateway](https://www.sibsapimarket.com/) payment integrations.
+
+PySIBS provides a clean API for payments, refunds, captures, cancellations, status
+checks and webhook verification. It is framework-agnostic and works in Django,
+FastAPI, Flask, Celery, CLI scripts — anywhere Python runs.
+
+> **Project status: Alpha.** The public API surface is intentionally small and
+> stable, but endpoint/field details are still being validated against SIBS' official
+> documentation. Every response exposes a `raw_response` so you are never blocked by a
+> field PySIBS has not yet normalized. See [Caveats](#caveats--unverified-details).
+
+## Features
+
+- Synchronous (`SIBSClient`) and asynchronous (`AsyncSIBSClient`) clients
+- Create payments, check status, refund, capture and cancel
+- Typed Pydantic models with normalized statuses (`PaymentStatus`)
+- Safe money handling with `Decimal` (floats are rejected)
+- Webhook parsing and configurable signature verification
+- A clear exception hierarchy — raw `httpx` errors never leak out
+- Fully typed (`py.typed`), `ruff` + `mypy --strict` clean
+
+## Installation
+
+```bash
+pip install pysibs
+```
+
+Requires Python 3.10+.
+
+## Configuration
+
+Construct a client directly:
+
+```python
+from pysibs import SIBSClient
+
+client = SIBSClient(
+    api_key="your_api_key",
+    terminal_id="your_terminal_id",
+    environment="sandbox",  # or "production"
+)
+```
+
+…or from environment variables (`SIBS_API_KEY`, `SIBS_TERMINAL_ID`,
+`SIBS_ENVIRONMENT`, and optionally `SIBS_CLIENT_ID`, `SIBS_WEBHOOK_SECRET`):
+
+```python
+client = SIBSClient.from_env()
+```
+
+The **core library never reads `.env`** — only the bundled examples do, via
+`python-dotenv`. See [`.env.example`](.env.example).
+
+## Create a payment
+
+```python
+payment = client.create_payment(
+    amount="10.00",                 # str, int or Decimal — never float
+    currency="EUR",
+    merchant_transaction_id="ORDER-123",
+    return_url="https://example.com/payment/success",
+    cancel_url="https://example.com/payment/cancel",
+    payment_methods=["CARD", "MBWAY", "MULTIBANCO"],
+)
+
+print(payment.id)
+print(payment.status)        # normalized PaymentStatus
+print(payment.redirect_url)
+print(payment.raw_response)  # untouched SIBS response
+```
+
+## Check payment status
+
+```python
+status = client.get_payment_status("payment_123")
+print(status.status)      # normalized PaymentStatus
+print(status.raw_status)  # original value from SIBS
+```
+
+## Refunds
+
+```python
+# Full refund
+client.refund_payment(payment_id="payment_123")
+
+# Partial refund
+client.refund_payment(payment_id="payment_123", amount="10.00", merchant_refund_id="REF-1001")
+```
+
+## Capture & cancel
+
+```python
+client.capture_payment(payment_id="payment_123", amount="25.50")
+client.cancel_payment("payment_123")
+```
+
+## Async usage
+
+```python
+from pysibs import AsyncSIBSClient
+
+async with AsyncSIBSClient.from_env() as client:
+    payment = await client.create_payment(amount="10.00", merchant_transaction_id="ORDER-1")
+```
+
+## Webhooks
+
+```python
+from pysibs import parse_webhook, verify_webhook_signature
+
+event = parse_webhook(raw_body)         # bytes, str or dict
+print(event.payment_id, event.status, event.raw_payload)
+
+is_valid = verify_webhook_signature(
+    payload=raw_body,
+    signature=request.headers.get("X-SIBS-Signature"),
+    secret="webhook_secret",
+)
+```
+
+SIBS' webhook signing scheme is not uniformly documented and may differ per
+product/environment. `verify_webhook_signature` defaults to HMAC-SHA256, but you can
+pass a custom `verifier` callable that matches whatever SIBS actually uses for your
+integration. **Always confirm the scheme against the official documentation.**
+
+## Error handling
+
+All exceptions inherit from `SIBSError`:
+
+| Exception | Raised when |
+| --- | --- |
+| `SIBSConfigurationError` | The client is misconfigured (missing credentials, bad environment). |
+| `SIBSValidationError` | Input fails local validation (e.g. a float amount, empty id). |
+| `SIBSAuthenticationError` | SIBS rejects credentials (HTTP 401/403). |
+| `SIBSAPIError` | Other API errors (carries `status_code` and `response_body`). |
+| `SIBSTimeoutError` | The request times out (or HTTP 408). |
+| `SIBSConnectionError` | SIBS cannot be reached (DNS/TCP/TLS). |
+| `SIBSInvalidWebhookSignature` | A webhook signature fails verification. |
+
+```python
+from pysibs import SIBSError, SIBSAuthenticationError
+
+try:
+    client.create_payment(amount="10.00", merchant_transaction_id="ORDER-1")
+except SIBSAuthenticationError:
+    ...  # bad credentials
+except SIBSError as exc:
+    ...  # any other PySIBS failure
+```
+
+## PCI DSS note
+
+This SDK does not store or process cardholder data by itself. However, some SIBS
+server-to-server card payment flows may require the merchant environment to be PCI DSS
+compliant. Always validate your integration scope with SIBS and your PCI advisor.
+
+PySIBS deliberately:
+
+- never stores PAN or CVV,
+- never logs `Authorization` headers or credentials,
+- ships no examples containing real card data.
+
+## Caveats — unverified details
+
+SIBS' public documentation does not pin down every endpoint, field name and signing
+detail unambiguously, and they can vary by product/environment. Where there was
+ambiguity, PySIBS:
+
+1. keeps the wire format isolated in `pysibs/_payloads.py` and base URLs in
+   `pysibs/config.py`, so they are trivial to adjust in one place;
+2. preserves the full `raw_response` / `raw_payload` on every model;
+3. never sends undocumented headers (e.g. idempotency — see `pysibs/idempotency.py`).
+
+Before going to production, verify the endpoints, payloads and webhook signature
+scheme against the current official SIBS documentation.
+
+## Python compatibility
+
+Tested on CPython 3.10, 3.11, 3.12 and 3.13.
+
+## Roadmap
+
+- `0.1.0` — `SIBSClient`/`AsyncSIBSClient`, create/status/refund/capture/cancel,
+  webhook parsing + verification, typed models, docs.
+- `0.2.0` — richer payment-method specific models (MB WAY, MULTIBANCO references).
+- `1.0.0` — stable API once the SIBS contract is fully confirmed end-to-end.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © Robert Benitez

pysibs-0.1.0/README.md

@@ -0,0 +1,196 @@
+# PySIBS
+
+A modern, typed, developer-friendly Python SDK for [SIBS Gateway](https://www.sibsapimarket.com/) payment integrations.
+
+PySIBS provides a clean API for payments, refunds, captures, cancellations, status
+checks and webhook verification. It is framework-agnostic and works in Django,
+FastAPI, Flask, Celery, CLI scripts — anywhere Python runs.
+
+> **Project status: Alpha.** The public API surface is intentionally small and
+> stable, but endpoint/field details are still being validated against SIBS' official
+> documentation. Every response exposes a `raw_response` so you are never blocked by a
+> field PySIBS has not yet normalized. See [Caveats](#caveats--unverified-details).
+
+## Features
+
+- Synchronous (`SIBSClient`) and asynchronous (`AsyncSIBSClient`) clients
+- Create payments, check status, refund, capture and cancel
+- Typed Pydantic models with normalized statuses (`PaymentStatus`)
+- Safe money handling with `Decimal` (floats are rejected)
+- Webhook parsing and configurable signature verification
+- A clear exception hierarchy — raw `httpx` errors never leak out
+- Fully typed (`py.typed`), `ruff` + `mypy --strict` clean
+
+## Installation
+
+```bash
+pip install pysibs
+```
+
+Requires Python 3.10+.
+
+## Configuration
+
+Construct a client directly:
+
+```python
+from pysibs import SIBSClient
+
+client = SIBSClient(
+    api_key="your_api_key",
+    terminal_id="your_terminal_id",
+    environment="sandbox",  # or "production"
+)
+```
+
+…or from environment variables (`SIBS_API_KEY`, `SIBS_TERMINAL_ID`,
+`SIBS_ENVIRONMENT`, and optionally `SIBS_CLIENT_ID`, `SIBS_WEBHOOK_SECRET`):
+
+```python
+client = SIBSClient.from_env()
+```
+
+The **core library never reads `.env`** — only the bundled examples do, via
+`python-dotenv`. See [`.env.example`](.env.example).
+
+## Create a payment
+
+```python
+payment = client.create_payment(
+    amount="10.00",                 # str, int or Decimal — never float
+    currency="EUR",
+    merchant_transaction_id="ORDER-123",
+    return_url="https://example.com/payment/success",
+    cancel_url="https://example.com/payment/cancel",
+    payment_methods=["CARD", "MBWAY", "MULTIBANCO"],
+)
+
+print(payment.id)
+print(payment.status)        # normalized PaymentStatus
+print(payment.redirect_url)
+print(payment.raw_response)  # untouched SIBS response
+```
+
+## Check payment status
+
+```python
+status = client.get_payment_status("payment_123")
+print(status.status)      # normalized PaymentStatus
+print(status.raw_status)  # original value from SIBS
+```
+
+## Refunds
+
+```python
+# Full refund
+client.refund_payment(payment_id="payment_123")
+
+# Partial refund
+client.refund_payment(payment_id="payment_123", amount="10.00", merchant_refund_id="REF-1001")
+```
+
+## Capture & cancel
+
+```python
+client.capture_payment(payment_id="payment_123", amount="25.50")
+client.cancel_payment("payment_123")
+```
+
+## Async usage
+
+```python
+from pysibs import AsyncSIBSClient
+
+async with AsyncSIBSClient.from_env() as client:
+    payment = await client.create_payment(amount="10.00", merchant_transaction_id="ORDER-1")
+```
+
+## Webhooks
+
+```python
+from pysibs import parse_webhook, verify_webhook_signature
+
+event = parse_webhook(raw_body)         # bytes, str or dict
+print(event.payment_id, event.status, event.raw_payload)
+
+is_valid = verify_webhook_signature(
+    payload=raw_body,
+    signature=request.headers.get("X-SIBS-Signature"),
+    secret="webhook_secret",
+)
+```
+
+SIBS' webhook signing scheme is not uniformly documented and may differ per
+product/environment. `verify_webhook_signature` defaults to HMAC-SHA256, but you can
+pass a custom `verifier` callable that matches whatever SIBS actually uses for your
+integration. **Always confirm the scheme against the official documentation.**
+
+## Error handling
+
+All exceptions inherit from `SIBSError`:
+
+| Exception | Raised when |
+| --- | --- |
+| `SIBSConfigurationError` | The client is misconfigured (missing credentials, bad environment). |
+| `SIBSValidationError` | Input fails local validation (e.g. a float amount, empty id). |
+| `SIBSAuthenticationError` | SIBS rejects credentials (HTTP 401/403). |
+| `SIBSAPIError` | Other API errors (carries `status_code` and `response_body`). |
+| `SIBSTimeoutError` | The request times out (or HTTP 408). |
+| `SIBSConnectionError` | SIBS cannot be reached (DNS/TCP/TLS). |
+| `SIBSInvalidWebhookSignature` | A webhook signature fails verification. |
+
+```python
+from pysibs import SIBSError, SIBSAuthenticationError
+
+try:
+    client.create_payment(amount="10.00", merchant_transaction_id="ORDER-1")
+except SIBSAuthenticationError:
+    ...  # bad credentials
+except SIBSError as exc:
+    ...  # any other PySIBS failure
+```
+
+## PCI DSS note
+
+This SDK does not store or process cardholder data by itself. However, some SIBS
+server-to-server card payment flows may require the merchant environment to be PCI DSS
+compliant. Always validate your integration scope with SIBS and your PCI advisor.
+
+PySIBS deliberately:
+
+- never stores PAN or CVV,
+- never logs `Authorization` headers or credentials,
+- ships no examples containing real card data.
+
+## Caveats — unverified details
+
+SIBS' public documentation does not pin down every endpoint, field name and signing
+detail unambiguously, and they can vary by product/environment. Where there was
+ambiguity, PySIBS:
+
+1. keeps the wire format isolated in `pysibs/_payloads.py` and base URLs in
+   `pysibs/config.py`, so they are trivial to adjust in one place;
+2. preserves the full `raw_response` / `raw_payload` on every model;
+3. never sends undocumented headers (e.g. idempotency — see `pysibs/idempotency.py`).
+
+Before going to production, verify the endpoints, payloads and webhook signature
+scheme against the current official SIBS documentation.
+
+## Python compatibility
+
+Tested on CPython 3.10, 3.11, 3.12 and 3.13.
+
+## Roadmap
+
+- `0.1.0` — `SIBSClient`/`AsyncSIBSClient`, create/status/refund/capture/cancel,
+  webhook parsing + verification, typed models, docs.
+- `0.2.0` — richer payment-method specific models (MB WAY, MULTIBANCO references).
+- `1.0.0` — stable API once the SIBS contract is fully confirmed end-to-end.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: see [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © Robert Benitez

pysibs-0.1.0/pyproject.toml

@@ -0,0 +1,118 @@
+[project]
+name = "pysibs"
+version = "0.1.0"
+description = "A modern Python SDK for SIBS Gateway payment integrations."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Robert Benitez" }]
+keywords = [
+  "sibs",
+  "payments",
+  "payment-gateway",
+  "mbway",
+  "multibanco",
+  "fintech",
+  "python-sdk",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Office/Business :: Financial",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov",
+  "pytest-asyncio",
+  "respx>=0.21",
+  "ruff",
+  "mypy",
+  "build",
+  "twine",
+]
+examples = [
+  "python-dotenv",
+  "fastapi",
+  "uvicorn",
+  "django",
+]
+
+[project.urls]
+Homepage = "https://github.com/robertruben98/pysibs"
+Repository = "https://github.com/robertruben98/pysibs"
+Issues = "https://github.com/robertruben98/pysibs/issues"
+Documentation = "https://github.com/robertruben98/pysibs#readme"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pysibs"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/pysibs",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+  "/CHANGELOG.md",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W", "C4", "SIM"]
+ignore = ["B008"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+disallow_untyped_defs = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = ["respx.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+  "integration: integration tests that hit a real SIBS sandbox (disabled by default)",
+]
+addopts = "-m 'not integration'"
+
+[tool.coverage.run]
+source = ["pysibs"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+  "\\.\\.\\.",
+]