altpay-py 0.1.0__tar.gz

altpay_py-0.1.0/LICENSE

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

altpay_py-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: altpay-py
+Version: 0.1.0
+Summary: Official Python SDK for the AltPay crypto-payments API (sync + async).
+Project-URL: Homepage, https://altpay.money
+Project-URL: Documentation, https://docs.altpay.money/
+Project-URL: Source, https://github.com/altpaysdk/py-sdk
+Author: AltPayments
+License: MIT
+License-File: LICENSE
+Keywords: altpay,api,crypto,payments,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# altpay-py
+
+Official Python SDK for the [AltPay](https://altpay.money) crypto-payments API. Synchronous
+and asynchronous clients, typed models, request signing and webhook verification in one
+package. Built on `httpx` and `pydantic` v2.
+
+```bash
+pip install altpay-py
+```
+
+```python
+import altpay  # the distribution is altpay-py; the import name is altpay
+```
+
+## Quick start
+
+```python
+from decimal import Decimal
+from altpay import AltPay, Credentials
+
+client = AltPay(Credentials(
+    merchant_id="YOUR_MERCHANT_ID",
+    api_key="vc_live_...",
+    api_secret="YOUR_API_SECRET",
+))
+
+invoice = client.invoices.create(
+    uuid="order-42",                 # your idempotency key / order reference
+    amount=Decimal("100.00"),
+    fiat_currency="USD",
+    url_callback="https://example.com/altpay/webhook",
+)
+print(invoice.url)                   # hosted checkout URL to redirect the payer to
+
+# later, check on it
+invoice = client.invoices.get(order_id=invoice.order_id)
+print(invoice.status)                # PaymentStatus.CREATED | PAYED | EXPIRED | ...
+```
+
+### Async
+
+The async client mirrors the sync one exactly; just `await` the calls.
+
+```python
+from altpay import AsyncAltPay, Credentials
+
+async with AsyncAltPay(creds) as client:
+    invoice = await client.invoices.create(
+        uuid="order-42", amount="100.00", fiat_currency="USD",
+    )
+    print(invoice.url)
+```
+
+## What you can do
+
+| Resource | Method | Endpoint |
+| --- | --- | --- |
+| `client.invoices` | `create(...)` | create an invoice |
+| | `get(order_id=... \| uuid=...)` | fetch one invoice |
+| | `list(status=..., cursor=..., limit=...)` | page through invoices |
+| | `services()` | available methods, limits and fees |
+| | `balance(fiat_currency=...)` | balance valued in one fiat, per asset |
+| | `create_wallet(network=..., order_id=...)` | static deposit wallet |
+| | `list_wallets(limit=..., offset=...)` | list static wallets |
+| `client.account` | `get()` | merchant + API-key identity |
+| | `balance()` | paid volume per method (native asset) |
+| | `statistics()` | aggregate counts and USD volume |
+
+## Webhooks
+
+AltPay POSTs a signed `payment.updated` event to your `url_callback` when an invoice is
+paid. **Always verify the signature before trusting the body**, and pass the *raw* request
+bytes (not the re-serialized JSON).
+
+```python
+from altpay import WebhookVerifier
+
+verifier = WebhookVerifier(WEBHOOK_SECRET, target="/altpay/webhook")
+
+# inside your handler (framework-agnostic):
+event = verifier.parse(raw_body, request_headers)   # raises AuthenticationError on a bad sig
+if event.status == "PAYED":
+    fulfil_order(event.merchant_reference)
+```
+
+`verifier.verify(raw_body, headers)` returns a bool if you prefer to branch yourself.
+
+## Errors
+
+Every failure is an `AltPayError`. Network problems raise `AltPayTransportError`; anything the
+API rejected raises an `APIError` subclass keyed by HTTP status. Each carries the server's
+machine-readable `detail`, a human `hint`, and the `request_id` for support.
+
+```python
+from altpay import AuthenticationError, RateLimitError, ValidationError, NotFoundError
+
+try:
+    client.invoices.create(uuid="o1", amount="100", fiat_currency="USD")
+except AuthenticationError as e:
+    ...   # bad credentials / clock skew / revoked key  (HTTP 401, detail="invalid_signature")
+except ValidationError as e:
+    ...   # a field failed validation                   (HTTP 400, detail="invalid_request")
+except RateLimitError as e:
+    sleep(e.retry_after or 1)                            # HTTP 429
+except NotFoundError as e:
+    ...                                                  # HTTP 404
+```
+
+The full catalogue, with every `detail` value and how to fix it, is at
+<https://docs.altpay.money/docs/http-codes>.
+
+## Configuration
+
+```python
+AltPay(
+    credentials,
+    base_url="https://api.altpay.money",  # override for staging
+    timeout=30.0,                          # per-request seconds
+    max_retries=2,                         # retry transient errors (5xx, 429, network) with backoff
+    http_client=my_httpx_client,           # bring your own httpx.Client (proxies, custom TLS)
+)
+```
+
+## Authentication, in brief
+
+Each request is signed with HMAC-SHA256 over a canonical string of the merchant id, API key,
+timestamp, nonce, body hash, method and path. The SDK does this for you; the secret never
+leaves your process. If you ever need the primitives (custom transport, testing), they live
+in `altpay.signing`. Full spec: <https://docs.altpay.money/docs/authentication>.
+
+## Requirements
+
+- Python 3.10+
+- `httpx >= 0.24`, `pydantic >= 2.0`
+
+## License
+
+MIT

altpay_py-0.1.0/README.md

@@ -0,0 +1,138 @@
+# altpay-py
+
+Official Python SDK for the [AltPay](https://altpay.money) crypto-payments API. Synchronous
+and asynchronous clients, typed models, request signing and webhook verification in one
+package. Built on `httpx` and `pydantic` v2.
+
+```bash
+pip install altpay-py
+```
+
+```python
+import altpay  # the distribution is altpay-py; the import name is altpay
+```
+
+## Quick start
+
+```python
+from decimal import Decimal
+from altpay import AltPay, Credentials
+
+client = AltPay(Credentials(
+    merchant_id="YOUR_MERCHANT_ID",
+    api_key="vc_live_...",
+    api_secret="YOUR_API_SECRET",
+))
+
+invoice = client.invoices.create(
+    uuid="order-42",                 # your idempotency key / order reference
+    amount=Decimal("100.00"),
+    fiat_currency="USD",
+    url_callback="https://example.com/altpay/webhook",
+)
+print(invoice.url)                   # hosted checkout URL to redirect the payer to
+
+# later, check on it
+invoice = client.invoices.get(order_id=invoice.order_id)
+print(invoice.status)                # PaymentStatus.CREATED | PAYED | EXPIRED | ...
+```
+
+### Async
+
+The async client mirrors the sync one exactly; just `await` the calls.
+
+```python
+from altpay import AsyncAltPay, Credentials
+
+async with AsyncAltPay(creds) as client:
+    invoice = await client.invoices.create(
+        uuid="order-42", amount="100.00", fiat_currency="USD",
+    )
+    print(invoice.url)
+```
+
+## What you can do
+
+| Resource | Method | Endpoint |
+| --- | --- | --- |
+| `client.invoices` | `create(...)` | create an invoice |
+| | `get(order_id=... \| uuid=...)` | fetch one invoice |
+| | `list(status=..., cursor=..., limit=...)` | page through invoices |
+| | `services()` | available methods, limits and fees |
+| | `balance(fiat_currency=...)` | balance valued in one fiat, per asset |
+| | `create_wallet(network=..., order_id=...)` | static deposit wallet |
+| | `list_wallets(limit=..., offset=...)` | list static wallets |
+| `client.account` | `get()` | merchant + API-key identity |
+| | `balance()` | paid volume per method (native asset) |
+| | `statistics()` | aggregate counts and USD volume |
+
+## Webhooks
+
+AltPay POSTs a signed `payment.updated` event to your `url_callback` when an invoice is
+paid. **Always verify the signature before trusting the body**, and pass the *raw* request
+bytes (not the re-serialized JSON).
+
+```python
+from altpay import WebhookVerifier
+
+verifier = WebhookVerifier(WEBHOOK_SECRET, target="/altpay/webhook")
+
+# inside your handler (framework-agnostic):
+event = verifier.parse(raw_body, request_headers)   # raises AuthenticationError on a bad sig
+if event.status == "PAYED":
+    fulfil_order(event.merchant_reference)
+```
+
+`verifier.verify(raw_body, headers)` returns a bool if you prefer to branch yourself.
+
+## Errors
+
+Every failure is an `AltPayError`. Network problems raise `AltPayTransportError`; anything the
+API rejected raises an `APIError` subclass keyed by HTTP status. Each carries the server's
+machine-readable `detail`, a human `hint`, and the `request_id` for support.
+
+```python
+from altpay import AuthenticationError, RateLimitError, ValidationError, NotFoundError
+
+try:
+    client.invoices.create(uuid="o1", amount="100", fiat_currency="USD")
+except AuthenticationError as e:
+    ...   # bad credentials / clock skew / revoked key  (HTTP 401, detail="invalid_signature")
+except ValidationError as e:
+    ...   # a field failed validation                   (HTTP 400, detail="invalid_request")
+except RateLimitError as e:
+    sleep(e.retry_after or 1)                            # HTTP 429
+except NotFoundError as e:
+    ...                                                  # HTTP 404
+```
+
+The full catalogue, with every `detail` value and how to fix it, is at
+<https://docs.altpay.money/docs/http-codes>.
+
+## Configuration
+
+```python
+AltPay(
+    credentials,
+    base_url="https://api.altpay.money",  # override for staging
+    timeout=30.0,                          # per-request seconds
+    max_retries=2,                         # retry transient errors (5xx, 429, network) with backoff
+    http_client=my_httpx_client,           # bring your own httpx.Client (proxies, custom TLS)
+)
+```
+
+## Authentication, in brief
+
+Each request is signed with HMAC-SHA256 over a canonical string of the merchant id, API key,
+timestamp, nonce, body hash, method and path. The SDK does this for you; the secret never
+leaves your process. If you ever need the primitives (custom transport, testing), they live
+in `altpay.signing`. Full spec: <https://docs.altpay.money/docs/authentication>.
+
+## Requirements
+
+- Python 3.10+
+- `httpx >= 0.24`, `pydantic >= 2.0`
+
+## License
+
+MIT

altpay_py-0.1.0/altpay/__init__.py

@@ -0,0 +1,119 @@
+"""AltPay - the official Python SDK for the AltPay crypto-payments API.
+
+Quick start (sync)::
+
+    from decimal import Decimal
+    from altpay import AltPay, Credentials
+
+    client = AltPay(Credentials(
+        merchant_id="YOUR_MERCHANT_ID",
+        api_key="vc_live_...",
+        api_secret="YOUR_API_SECRET",
+    ))
+    invoice = client.invoices.create(
+        uuid="order-42",
+        amount=Decimal("100.00"),
+        fiat_currency="USD",
+        url_callback="https://example.com/altpay/webhook",
+    )
+    print(invoice.url)
+
+Quick start (async)::
+
+    from altpay import AsyncAltPay, Credentials
+
+    async with AsyncAltPay(creds) as client:
+        invoice = await client.invoices.create(uuid="order-42", amount="100.00", fiat_currency="USD")
+
+Verifying a webhook::
+
+    from altpay import WebhookVerifier
+    verifier = WebhookVerifier(webhook_secret, target="/altpay/webhook")
+    event = verifier.parse(raw_body, request_headers)  # raises on a bad signature
+
+Documentation: https://docs.altpay.money/docs
+"""
+
+from .__meta__ import __version__
+from .client import AltPay, AsyncAltPay
+from .credentials import Credentials
+from .enums import FiatCurrency, MerchantStatus, PaymentMethod, PaymentStatus, WithdrawalStatus
+from .errors import (
+    AltPayError,
+    AltPayTransportError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    Forbidden,
+    NotFoundError,
+    PermissionError_,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    Account,
+    AssetBalance,
+    AssetBalanceItem,
+    Balance,
+    BalanceAsset,
+    Invoice,
+    InvoicePage,
+    MethodBalance,
+    MethodBalanceItem,
+    Service,
+    ServiceCommission,
+    Statistics,
+    Wallet,
+    WalletDeposit,
+    WebhookEvent,
+    Withdrawal,
+    WithdrawalFee,
+)
+from .webhook import WebhookVerifier
+
+__all__ = [
+    "__version__",
+    # Clients
+    "AltPay",
+    "AsyncAltPay",
+    "Credentials",
+    # Webhooks
+    "WebhookVerifier",
+    # Enums
+    "PaymentStatus",
+    "PaymentMethod",
+    "FiatCurrency",
+    "MerchantStatus",
+    "WithdrawalStatus",
+    # Models
+    "Invoice",
+    "InvoicePage",
+    "Service",
+    "ServiceCommission",
+    "Balance",
+    "BalanceAsset",
+    "AssetBalance",
+    "AssetBalanceItem",
+    "Wallet",
+    "WalletDeposit",
+    "Account",
+    "MethodBalance",
+    "MethodBalanceItem",
+    "Statistics",
+    "Withdrawal",
+    "WithdrawalFee",
+    "WebhookEvent",
+    # Errors
+    "AltPayError",
+    "AltPayTransportError",
+    "APIError",
+    "AuthenticationError",
+    "Forbidden",
+    "PermissionError_",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+]

altpay_py-0.1.0/altpay/__meta__.py

@@ -0,0 +1,5 @@
+"""Package metadata, kept in one place so the version has a single source of truth."""
+
+__version__ = "0.1.0"
+__title__ = "altpay-py"
+__user_agent__ = f"altpay-py/{__version__}"

altpay_py-0.1.0/altpay/client/__init__.py

@@ -0,0 +1,6 @@
+"""HTTP clients: the synchronous :class:`AltPay` and asynchronous :class:`AsyncAltPay`."""
+
+from .async_client import AsyncAltPay
+from .sync_client import AltPay
+
+__all__ = ["AltPay", "AsyncAltPay"]

altpay_py-0.1.0/altpay/client/async_client.py

@@ -0,0 +1,114 @@
+"""The asynchronous client, :class:`AsyncAltPay`.
+
+The async twin of :class:`~altpay.client.sync_client.AltPay`. Same API, same resources, same
+request/response logic from :mod:`altpay.client.base`; only the I/O is awaited.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, TypeVar
+
+import httpx
+
+from ..credentials import Credentials
+from ..errors import AltPayTransportError, RateLimitError, ServerError
+from ..methods.account import AccountResource
+from ..methods.base import APICall
+from ..methods.invoices import Invoices
+from ..methods.withdrawals import Withdrawals
+from .base import parse_response, prepare
+from .sync_client import DEFAULT_BASE_URL, _backoff, _retry_delay
+
+T = TypeVar("T")
+
+
+class AsyncAltPay:
+    """Asynchronous AltPay API client.
+
+    Example::
+
+        from decimal import Decimal
+        from altpay import AsyncAltPay, Credentials
+
+        async with AsyncAltPay(Credentials(
+            merchant_id="...", api_key="vc_live_...", api_secret="...",
+        )) as client:
+            invoice = await client.invoices.create(
+                uuid="order-1", amount=Decimal("100.00"), fiat_currency="USD",
+            )
+            print(invoice.url)
+
+    Args mirror :class:`~altpay.client.sync_client.AltPay`; ``http_client`` here is an
+    :class:`httpx.AsyncClient`.
+
+    API reference: https://docs.altpay.money/docs
+    """
+
+    def __init__(
+        self,
+        credentials: Credentials,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._credentials = credentials
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+        #: Invoice and static-wallet operations.
+        self.invoices = Invoices(self.call)
+        #: Payout (withdrawal) operations.
+        self.withdrawals = Withdrawals(self.call)
+        #: Account identity, balance and statistics.
+        self.account = AccountResource(self.call)
+
+    async def __aenter__(self) -> "AsyncAltPay":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool (unless you supplied your own client)."""
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def call(self, call: APICall[T]) -> T:
+        """Execute a described :class:`~altpay.methods.base.APICall` and return its typed result."""
+        request = prepare(
+            credentials=self._credentials,
+            base_url=self._base_url,
+            path=call.path,
+            payload=call.payload,
+        )
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(
+                    request.method, request.url, headers=request.headers, content=request.content
+                )
+            except httpx.HTTPError as exc:
+                if attempt >= self._max_retries:
+                    raise AltPayTransportError(str(exc)) from exc
+                await asyncio.sleep(_backoff(attempt))
+                attempt += 1
+                continue
+
+            try:
+                result = parse_response(
+                    status_code=response.status_code,
+                    body_text=response.text,
+                    headers=response.headers,
+                )
+            except (RateLimitError, ServerError) as exc:
+                if attempt >= self._max_retries:
+                    raise
+                await asyncio.sleep(_retry_delay(exc, attempt))
+                attempt += 1
+                continue
+            return call.parse(result)