arionpay 1.0.0__py3-none-any.whl

arionpay/__init__.py

@@ -0,0 +1,23 @@
+"""Official Python client for ArionPay: create crypto invoices and verify webhooks."""
+
+from .client import DEFAULT_BASE_URL, EVENT_TYPES, SCENARIOS, VERSION, ArionPay, normalize_invoice_read
+from .errors import ArionPayError, SignatureError
+from .webhook import DEFAULT_TOLERANCE_SEC, is_test_event, is_valid_signature, parse_signature_header, sign_request, verify_webhook
+
+__version__ = VERSION
+__all__ = [
+    "ArionPay",
+    "ArionPayError",
+    "SignatureError",
+    "verify_webhook",
+    "is_valid_signature",
+    "is_test_event",
+    "parse_signature_header",
+    "sign_request",
+    "normalize_invoice_read",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOLERANCE_SEC",
+    "EVENT_TYPES",
+    "SCENARIOS",
+    "VERSION",
+]

arionpay/client.py

@@ -0,0 +1,276 @@
+"""Client for the ArionPay merchant API. Use it on your server only: it holds your secret key."""
+
+import json
+import platform
+import re
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple
+
+from .errors import ArionPayError
+from .webhook import Body, sign_request, verify_webhook
+
+VERSION = "1.0.0"
+DEFAULT_BASE_URL = "https://merchant.arionpay.com"
+
+_PK = re.compile(r"^pk_[A-Za-z0-9_-]{8,64}$")
+_ID = re.compile(r"^[0-9a-fA-F]{24}$")
+
+# (method, url, headers, body or None, timeout seconds) -> (status, headers, body bytes); raises OSError when unreachable
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Tuple[int, Mapping[str, str], bytes]]
+
+SCENARIOS = ("detected", "confirm", "exact", "underpaid_1pct", "underpaid_5pct", "overpaid", "partial_half", "late")
+EVENT_TYPES = ("invoice.pending", "invoice.partial", "invoice.paid", "invoice.expired", "invoice.needs_review")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+def _urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> Tuple[int, Mapping[str, str], bytes]:
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with _opener.open(req, timeout=timeout) as resp:
+            return resp.status, dict(resp.headers.items()), resp.read()
+    except urllib.error.HTTPError as e:
+        return e.code, dict(e.headers.items()) if e.headers else {}, e.read() or b""
+
+
+def _s(v: Any, default: str = "") -> str:
+    return default if v is None else str(v)
+
+
+def normalize_invoice_read(r: Mapping[str, Any]) -> Dict[str, Any]:
+    """Turn the signed read (GET /api/v1/invoices/<id>) into the webhook invoice field names."""
+    out = {
+        "id": _s(r.get("invoiceId", r.get("id"))),
+        "status": _s(r.get("status")).lower(),
+        "orderId": r.get("orderId"),
+        "amountFiat": r.get("amountFiat"),
+        "currency": _s(r.get("currency")),
+        "asset": _s(r.get("settledCurrency")),
+        "network": _s(r.get("network")),
+        "amountCrypto": _s(r.get("amountExpected")),
+        "paidCrypto": _s(r.get("amountReceived"), "0"),
+        "confirmedCrypto": _s(r.get("amountConfirmed"), "0"),
+        "overpaid": r.get("overpaid") is True,
+        "underpaidWithinTolerance": r.get("underpaidWithinTolerance") is True,
+        "late": r.get("late") is True,
+        "needsReview": r.get("needsReview") is True,
+        "manual": r.get("manual") is True,
+        "test": r.get("test") is True,
+        "transactions": r.get("transactions") if isinstance(r.get("transactions"), list) else [],
+        "metadata": r.get("metadata") if isinstance(r.get("metadata"), dict) else {},
+        "paidAt": r.get("settledAt"),
+        "txHash": r.get("txHash"),
+        "confirmations": r.get("confirmations", 0),
+        "requiredConfirmations": r.get("requiredConfirmations", 0),
+        "raw": dict(r),
+    }  # type: Dict[str, Any]
+    if "paidVia" in r:
+        out["paidVia"] = r.get("paidVia")
+    return out
+
+
+class ArionPay:
+    """ArionPay merchant API client.
+
+        client = ArionPay(api_key=os.environ["ARIONPAY_API_KEY"], api_secret=os.environ["ARIONPAY_API_SECRET"])
+        invoice = client.create_invoice(amount="49.90", currency="USD", order_id="1001")
+        # send the customer to invoice["invoiceUrl"]
+
+    Returned invoices are dicts with the same field names as the webhook's data.invoice (camelCase), so one function
+    can handle a webhook and a read.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        webhook_secret: str = "",
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 20.0,
+        max_attempts: int = 3,
+        transport: Optional[Transport] = None,
+        app_info: str = "",
+    ) -> None:
+        if not isinstance(api_key, str) or not _PK.match(api_key):
+            raise ValueError("api_key must be your store API key (it starts with pk_).")
+        if not api_secret:
+            raise ValueError("api_secret is required (your store API secret, it starts with sk_).")
+        parts = urllib.parse.urlsplit(base_url)
+        if parts.scheme not in ("http", "https") or not parts.netloc:
+            raise ValueError("base_url must be an http(s) address.")
+        self._api_key = api_key
+        self._api_secret = api_secret
+        self._webhook_secret = webhook_secret
+        self._origin = "%s://%s" % (parts.scheme, parts.netloc)
+        self._base_path = parts.path.rstrip("/")
+        self._timeout = float(timeout)
+        self._max_attempts = max(1, min(5, int(max_attempts)))
+        self._transport = transport or _urllib_transport
+        self._user_agent = "arionpay-python/%s python/%s%s" % (VERSION, platform.python_version(), (" " + app_info) if app_info else "")
+
+    # -- invoices -------------------------------------------------------------------------------------------------
+
+    def create_invoice(
+        self,
+        amount: Any,
+        currency: str = "USD",
+        order_id: Optional[str] = None,
+        description: Optional[str] = None,
+        customer_email: Optional[str] = None,
+        success_url: Optional[str] = None,
+        cancel_url: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        asset: Optional[str] = None,
+        allowed_assets: Optional[List[str]] = None,
+        expires_min: Optional[int] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        test: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Create an invoice. Returns {"id", "invoiceUrl", "status", "amountFiat", "currency", "asset", "address",
+        "amountCrypto", "expiresAt", "orderId", "raw"}. Send the customer to invoiceUrl.
+
+        Safe to retry: each call carries an idempotency key (a random one when you pass none), so a repeat after a
+        network error returns the same invoice. Pass your own key (e.g. "order-1001-1") to be safe across restarts.
+        The customer coming back to success_url does NOT prove payment: wait for the invoice.paid webhook.
+        """
+        if amount is None or isinstance(amount, bool):
+            raise ValueError("amount is required.")
+        fields = {
+            "amount": str(amount),
+            "currency": currency,
+            "orderId": order_id,
+            "description": description,
+            "customerEmail": customer_email,
+            "successUrl": success_url,
+            "cancelUrl": cancel_url,
+            "callbackUrl": callback_url,
+            "asset": asset,
+            "allowedAssets": allowed_assets,
+            "expiresMin": expires_min,
+            "metadata": metadata,
+            "idempotencyKey": idempotency_key or "sdk_" + str(uuid.uuid4()),
+            "test": test,
+        }
+        body = {k: v for k, v in fields.items() if v is not None}
+        r = self._request("POST", "/api/v1/invoices", body, retry_safe=True)
+        d = r.get("data") if isinstance(r.get("data"), dict) else r
+        return {
+            "id": _s(d.get("id", r.get("id"))),
+            "invoiceUrl": _s(d.get("invoice_url", r.get("invoice_url"))),
+            "status": _s(d.get("status"), "new"),
+            "amountFiat": d.get("amount_fiat"),
+            "currency": _s(d.get("currency"), currency),
+            "asset": d.get("asset"),
+            "address": d.get("address"),
+            "amountCrypto": d.get("amount_crypto"),
+            "expiresAt": d.get("expires_at"),
+            "orderId": d.get("order_id", order_id),
+            "raw": r,
+        }
+
+    def get_invoice(self, invoice_id: str) -> Dict[str, Any]:
+        """Read an invoice, signed, straight from ArionPay (webhook field names). Use it to double-check, or to poll."""
+        self._check_id(invoice_id)
+        return normalize_invoice_read(self._request("GET", "/api/v1/invoices/" + invoice_id, None, retry_safe=True))
+
+    def simulate_payment(self, invoice_id: str, scenario: str = "exact") -> Dict[str, Any]:
+        """Sandbox: move a TEST invoice through a payment scenario; webhooks then fire as for a real payment.
+        Create the test invoice with asset=... (e.g. "USDT_TRC20") so a coin is chosen."""
+        self._check_id(invoice_id)
+        if scenario not in SCENARIOS:
+            raise ValueError("scenario must be one of: " + ", ".join(SCENARIOS))
+        return self._request("POST", "/api/v1/invoices/%s/simulate" % invoice_id, {"scenario": scenario}, retry_safe=False)
+
+    def send_test_webhook(self, event_type: str = "invoice.paid") -> Dict[str, Any]:
+        """Ask ArionPay to send a signed sample event to your store's webhook address. It never describes a real order."""
+        return self._request("POST", "/api/v1/webhooks/test", {"eventType": event_type}, retry_safe=False)
+
+    def currencies(self) -> List[Dict[str, Any]]:
+        """Coins you can pass as asset / allowed_assets (e.g. "USDT_TRC20", "BTC", "LTC"), with USD rates."""
+        r = self._request("GET", "/api/v1/currencies", None, retry_safe=True, signed=False)
+        return r.get("currencies") if isinstance(r.get("currencies"), list) else []
+
+    def rates(self, currency: str = "USD") -> Dict[str, Any]:
+        """Current coin prices in one fiat currency."""
+        return self._request("GET", "/api/v1/rates?currency=" + urllib.parse.quote(currency), None, retry_safe=True, signed=False)
+
+    def verify_webhook(self, raw_body: Body, signature_header: Optional[str], tolerance_sec: int = 300) -> Dict[str, Any]:
+        """Check a webhook with the webhook_secret given to the constructor. See arionpay.verify_webhook."""
+        return verify_webhook(raw_body, signature_header, self._webhook_secret, tolerance_sec)
+
+    # -- transport ------------------------------------------------------------------------------------------------
+
+    @staticmethod
+    def _check_id(invoice_id: str) -> None:
+        if not isinstance(invoice_id, str) or not _ID.match(invoice_id):
+            raise ValueError("Invoice id must be the 24-character id ArionPay returned.")
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]], retry_safe: bool, signed: bool = True) -> Dict[str, Any]:
+        raw = None if body is None else json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        replay_retry_used = False
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                return self._send(method, path, raw, signed)
+            except ArionPayError as e:
+                # Two identical signed requests in the same second have the same signature; only the first is accepted.
+                if e.status == 401 and "already used" in e.message.lower() and not replay_retry_used:
+                    replay_retry_used = True
+                    time.sleep(1.1)
+                    continue
+                retry_after = 0
+                if isinstance(e.body, dict):
+                    try:
+                        retry_after = int(e.body.get("retryAfterSec") or 0)
+                    except (TypeError, ValueError):
+                        retry_after = 0
+                temporary = e.status in (0, 502, 503, 504) or (e.status == 429 and retry_after <= 5)
+                if not retry_safe or not temporary or attempt >= self._max_attempts:
+                    raise
+                time.sleep(max(1, retry_after) if e.status == 429 else 0.5 * (3 ** (attempt - 1)))
+
+    def _send(self, method: str, path: str, raw: Optional[bytes], signed: bool) -> Dict[str, Any]:
+        path_only, _, query = path.partition("?")
+        full_path = self._base_path + path_only + ("?" + query if query else "")
+        headers = {"Accept": "application/json", "User-Agent": self._user_agent}
+        if signed:
+            ts = int(time.time())
+            headers["x-api-key"] = self._api_key
+            headers["x-timestamp"] = str(ts)
+            headers["x-signature"] = sign_request(self._api_secret, ts, method, full_path, raw or b"")
+        if raw is not None:
+            headers["Content-Type"] = "application/json"
+        try:
+            status, resp_headers, data = self._transport(method, self._origin + full_path, headers, raw, self._timeout)
+        except (OSError, socket.timeout) as e:
+            raise ArionPayError("Could not reach ArionPay: %s" % (e,), 0, "network_error")
+        try:
+            decoded = json.loads(data.decode("utf-8")) if data else {}
+        except (ValueError, UnicodeDecodeError):
+            decoded = {}
+        obj = decoded if isinstance(decoded, dict) else {}
+        if status < 200 or status >= 300:
+            message = obj.get("error") if isinstance(obj.get("error"), str) else obj.get("message") if isinstance(obj.get("message"), str) else "HTTP %d" % status
+            lower = {k.lower(): v for k, v in dict(resp_headers or {}).items()}
+            try:
+                retry_after = int(lower.get("retry-after", 0) or 0)
+            except (TypeError, ValueError):
+                retry_after = 0
+            err_body = dict(obj)
+            if retry_after:
+                err_body["retryAfterSec"] = retry_after
+            raise ArionPayError("ArionPay API error (%d): %s" % (status, message), status, obj.get("code") if isinstance(obj.get("code"), str) else "", err_body)
+        return obj

arionpay/errors.py

@@ -0,0 +1,24 @@
+"""Errors raised by the ArionPay client. Messages never contain your secret key."""
+
+from typing import Any, Optional
+
+
+class ArionPayError(Exception):
+    """Any failure talking to the ArionPay API.
+
+    Attributes:
+        status: HTTP status, 0 when ArionPay could not be reached.
+        code: machine-readable code when the API sent one, e.g. "idempotency_key_reused", "rate_limited".
+        body: decoded error body, if any.
+    """
+
+    def __init__(self, message: str, status: int = 0, code: str = "", body: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body
+
+
+class SignatureError(Exception):
+    """A webhook that must not be trusted: bad or missing signature, stale timestamp, or not an event."""

arionpay/webhook.py

@@ -0,0 +1,114 @@
+"""Request and webhook signatures, matching the ArionPay backend.
+
+Signed API requests:
+    POST: x-signature = hex HMAC-SHA256(secret key, "<timestamp>.<raw body>")
+    GET:  x-signature = hex HMAC-SHA256(secret key, "<timestamp>.GET <path and query>")
+
+Webhooks:
+    ArionPay-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(webhook secret, "<t>.<raw body>")>
+"""
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Dict, Optional, Tuple, Union
+
+from .errors import SignatureError
+
+DEFAULT_TOLERANCE_SEC = 300
+"""Webhooks signed more than this many seconds ago (or ahead) are refused. ArionPay signs again on every retry."""
+
+_HEX64 = re.compile(r"^[0-9a-fA-F]{64}$")
+_DIGITS = re.compile(r"^[0-9]{1,12}$")
+
+Body = Union[bytes, bytearray, str]
+
+
+def _as_bytes(raw: Body) -> bytes:
+    if isinstance(raw, (bytes, bytearray)):
+        return bytes(raw)
+    if isinstance(raw, str):
+        return raw.encode("utf-8")
+    raise SignatureError("raw_body must be the raw request body (bytes or str), not a parsed object.")
+
+
+def sign_request(secret_key: str, timestamp: int, method: str, path_and_query: str, raw_body: Body = b"") -> str:
+    """Signature for one request to the merchant API (lower-case hex)."""
+    if method.upper() == "GET":
+        data = ("%d.GET %s" % (timestamp, path_and_query)).encode("utf-8")
+    else:
+        data = ("%d." % timestamp).encode("utf-8") + _as_bytes(raw_body)
+    return hmac.new(secret_key.encode("utf-8"), data, hashlib.sha256).hexdigest()
+
+
+def parse_signature_header(header: Optional[str]) -> Optional[Tuple[int, str]]:
+    """Read an ArionPay-Signature header. Returns (t, v1) or None when it is malformed."""
+    values = {}  # type: Dict[str, str]
+    for part in str(header or "").split(","):
+        if "=" in part:
+            k, v = part.split("=", 1)
+            values[k.strip()] = v.strip()
+    t, v1 = values.get("t", ""), values.get("v1", "")
+    if not _DIGITS.match(t) or not _HEX64.match(v1):
+        return None
+    return int(t), v1.lower()
+
+
+def is_valid_signature(
+    raw_body: Body, header: Optional[str], webhook_secret: str, tolerance_sec: int = DEFAULT_TOLERANCE_SEC, now: Optional[int] = None
+) -> bool:
+    """True when the header is a valid, fresh signature of exactly this body. Never raises for bad input."""
+    if not webhook_secret:
+        return False
+    parsed = parse_signature_header(header)
+    if parsed is None:
+        return False
+    t, v1 = parsed
+    now = int(time.time()) if now is None else int(now)
+    if abs(now - t) > tolerance_sec:
+        return False
+    try:
+        body = _as_bytes(raw_body)
+    except SignatureError:
+        return False
+    expected = hmac.new(webhook_secret.encode("utf-8"), ("%d." % t).encode("utf-8") + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, v1)
+
+
+def verify_webhook(
+    raw_body: Body, header: Optional[str], webhook_secret: str, tolerance_sec: int = DEFAULT_TOLERANCE_SEC, now: Optional[int] = None
+) -> Dict[str, Any]:
+    """Check a webhook and return the event as a dict. Raises SignatureError when it must not be trusted.
+
+    raw_body must be the exact bytes ArionPay sent (Flask: request.get_data(), Django: request.body,
+    FastAPI: await request.body()), not a parsed and re-serialised object.
+    """
+    if not webhook_secret:
+        raise SignatureError("The webhook secret is empty. Copy it from the Webhooks page of your ArionPay dashboard (it starts with whsec_).")
+    body = _as_bytes(raw_body)
+    if parse_signature_header(header) is None:
+        raise SignatureError("Missing or malformed ArionPay-Signature header.")
+    if not is_valid_signature(body, header, webhook_secret, tolerance_sec, now):
+        raise SignatureError("Invalid webhook signature or stale timestamp. Check the webhook secret and your server clock.")
+    try:
+        event = json.loads(body.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        raise SignatureError("The webhook body is not JSON.")
+    if (
+        not isinstance(event, dict)
+        or not isinstance(event.get("id"), str)
+        or not event["id"]
+        or not isinstance(event.get("type"), str)
+        or not isinstance(event.get("data"), dict)
+        or not isinstance(event["data"].get("invoice"), dict)
+    ):
+        raise SignatureError("The webhook body is not an ArionPay event.")
+    return event
+
+
+def is_test_event(event: Dict[str, Any]) -> bool:
+    """True for events made by "Send test webhook": a made-up invoice that must never change an order."""
+    invoice = (event.get("data") or {}).get("invoice") or {}
+    return bool(event.get("test")) or str(event.get("id", "")).startswith("evt_test_") or str(invoice.get("id", "")).startswith("inv_test_")

arionpay-1.0.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: arionpay
+Version: 1.0.0
+Summary: Official Python client for ArionPay: create crypto invoices and verify webhooks. Payments go straight to your own wallet.
+Author-email: ArionPay <info@arionpay.com>
+License-Expression: MIT
+Project-URL: Homepage, https://arionpay.com
+Project-URL: Documentation, https://arionpay.com/knowledge-base
+Project-URL: Source, https://github.com/ArionPay-Dev/arionpay-python
+Project-URL: Changelog, https://github.com/ArionPay-Dev/arionpay-python/blob/main/CHANGELOG.md
+Keywords: arionpay,crypto,payments,bitcoin,usdt,payment-gateway,webhook
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ArionPay for Python
+
+Official Python client for [ArionPay](https://arionpay.com). Create crypto invoices, send customers to the payment page, and check webhooks. The money goes straight to your own wallet: ArionPay never holds it.
+
+- No dependencies (standard library only). Python 3.8 or newer.
+- Works with Flask, Django, FastAPI or plain scripts.
+- Safe retries: every invoice request carries an idempotency key, so a network error can never create two invoices.
+
+```bash
+pip install arionpay
+```
+
+## Keys
+
+In your ArionPay dashboard, open your store:
+
+| Value | Where | Starts with |
+| --- | --- | --- |
+| API key | Store page, **API key** | `pk_` |
+| API secret | Store page, **API secret** (asks for your authenticator code) | `sk_` |
+| Webhook secret | **Webhooks** page, **signing secret** | `whsec_` |
+
+Keep them on your server, for example in environment variables.
+
+## Take a payment
+
+```python
+import os
+from arionpay import ArionPay
+
+arionpay = ArionPay(
+    api_key=os.environ["ARIONPAY_API_KEY"],
+    api_secret=os.environ["ARIONPAY_API_SECRET"],
+    webhook_secret=os.environ["ARIONPAY_WEBHOOK_SECRET"],
+)
+
+invoice = arionpay.create_invoice(
+    amount="49.90",
+    currency="USD",
+    order_id="1001",
+    success_url="https://shop.example.com/thanks/1001",
+    cancel_url="https://shop.example.com/cart",
+    metadata={"user_id": 42},
+)
+# send the customer to invoice["invoiceUrl"]
+```
+
+The customer coming back to `success_url` does **not** prove they paid. Deliver the order when the `invoice.paid` webhook arrives (or when `get_invoice` says `paid`).
+
+Invoices are returned as dicts with the same field names as the webhook's `data.invoice` (`id`, `status`, `orderId`, `amountFiat`, `currency`, `asset`, `paidCrypto`, `transactions`, `test`, `metadata`, ...), so one function can handle a webhook and a read.
+
+## Webhooks
+
+Set your webhook address on the **Webhooks** page of the dashboard (a public `https://` address), or per invoice with `callback_url`. Check the signature against the **raw** body, before you parse it.
+
+### Flask
+
+```python
+from flask import Flask, request
+from arionpay import SignatureError, is_test_event
+
+app = Flask(__name__)
+
+@app.post("/arionpay/webhook")
+def arionpay_webhook():
+    try:
+        event = arionpay.verify_webhook(request.get_data(), request.headers.get("ArionPay-Signature"))
+    except SignatureError:
+        return {"error": "invalid_signature"}, 401
+    if is_test_event(event):
+        return {"received": True}  # "Send test webhook": not a real order
+    handle_event(event)
+    return {"received": True}
+```
+
+### Django
+
+```python
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+from arionpay import SignatureError, is_test_event
+
+@csrf_exempt
+@require_POST
+def arionpay_webhook(request):
+    try:
+        event = arionpay.verify_webhook(request.body, request.headers.get("ArionPay-Signature"))
+    except SignatureError:
+        return JsonResponse({"error": "invalid_signature"}, status=401)
+    if not is_test_event(event):
+        handle_event(event)
+    return JsonResponse({"received": True})
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Request, Response
+from arionpay import SignatureError, is_test_event
+
+app = FastAPI()
+
+@app.post("/arionpay/webhook")
+async def arionpay_webhook(request: Request):
+    raw = await request.body()
+    try:
+        event = arionpay.verify_webhook(raw, request.headers.get("arionpay-signature"))
+    except SignatureError:
+        return Response(status_code=401)
+    if not is_test_event(event):
+        handle_event(event)
+    return {"received": True}
+```
+
+### Handling an event
+
+```python
+def handle_event(event):
+    if already_processed(event["id"]):          # the same event can arrive more than once
+        return
+    invoice = event["data"]["invoice"]
+    order = find_order(invoice["orderId"])
+    if event["type"] == "invoice.paid" and order and not order.paid:
+        same_total = f"{float(order.total):.2f}" == f"{float(invoice['amountFiat']):.2f}"
+        if same_total and order.currency == invoice["currency"] and invoice["test"] == order.is_test:
+            mark_order_paid(order, invoice)      # deliver here
+    remember_processed(event["id"])
+```
+
+| Event | Meaning | What to do |
+| --- | --- | --- |
+| `invoice.pending` | A payment was seen on the network and waits for confirmations. | Show "payment on its way". Do not deliver yet. |
+| `invoice.partial` | Less than the full amount arrived. The invoice stays open for the rest. | Do not deliver. |
+| `invoice.paid` | Fully paid and confirmed. Also sent when you accept a payment by hand in the dashboard. | Deliver the order. |
+| `invoice.expired` | Time ran out without full payment. A late payment can still make it `paid`. | Keep the order unpaid. |
+| `invoice.needs_review` | Something needs a person, for example more money arrived after the invoice was paid. | Tell a human. Do not change the order. |
+
+ArionPay sends again when your server does not answer `2xx` (for about 3 days).
+
+### Rules for a safe integration
+
+1. Check the signature on the raw body. Never trust a webhook you could not verify.
+2. Deliver only on `invoice.paid` (or `get_invoice(...)["status"] == "paid"`).
+3. Match the invoice to your order: your `order_id` or `metadata`, and the same amount and currency as the order's current total.
+4. Ignore test events (`is_test_event(event)`), and in your live shop ignore invoices with `"test": True`.
+5. Handle each `event["id"]` once, and answer `2xx` quickly.
+6. Do not compare crypto amounts yourself. ArionPay decides when an invoice is paid, including payments inside your store's payment tolerance and payments you accept in Payment Radar.
+
+## Test without real money
+
+```python
+invoice = arionpay.create_invoice(amount="10", order_id="test-1", asset="USDT_TRC20", test=True)
+arionpay.simulate_payment(invoice["id"], "exact")   # your webhook gets invoice.paid, like a real payment
+```
+
+Scenarios: `exact`, `detected`, `confirm`, `underpaid_1pct`, `underpaid_5pct`, `overpaid`, `partial_half`, `late`.
+
+`arionpay.send_test_webhook("invoice.paid")` sends a signed sample event to your store's webhook address. It describes a made-up invoice (`inv_test_...`) and must never change an order.
+
+## Reference
+
+| Method | Returns |
+| --- | --- |
+| `create_invoice(amount, currency="USD", order_id=None, ...)` | `{"id", "invoiceUrl", "status", "amountFiat", "currency", "asset", "address", "amountCrypto", "expiresAt", "orderId"}` |
+| `get_invoice(invoice_id)` | The invoice, with the webhook field names. |
+| `simulate_payment(invoice_id, scenario)` | Sandbox only (test invoices). |
+| `send_test_webhook(event_type="invoice.paid")` | `{"delivered", "httpStatus", "eventId"}` |
+| `currencies()` | Coins you can pass as `asset` / `allowed_assets`. |
+| `rates(currency="USD")` | Current coin prices. |
+| `verify_webhook(raw_body, signature_header)` | The event dict, or raises `SignatureError`. Also a module function taking the secret as third argument. |
+
+`create_invoice` keyword arguments: `currency`, `order_id`, `description`, `customer_email`, `success_url`, `cancel_url`, `callback_url`, `asset`, `allowed_assets`, `expires_min` (5 to 1440), `metadata`, `idempotency_key`, `test`.
+
+Errors are `ArionPayError` with `.status` (HTTP status, `0` when ArionPay could not be reached), `.code` (for example `idempotency_key_reused`, `rate_limited`, `unknown_asset`) and `.message`. Messages never contain your secret.
+
+Options: `api_key`, `api_secret`, `webhook_secret`, `base_url` (default `https://merchant.arionpay.com`), `timeout` (seconds, default 20), `max_attempts` (default 3), `app_info`.
+
+## License
+
+MIT

arionpay-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+arionpay/__init__.py,sha256=KUJ67iRdP2xPpvbY_NQSY2UFfds_T8QHrbZEyBfK6JI,723
+arionpay/client.py,sha256=H3Asfbb4tinEcgjY8AvH1IKTu4xQWePxwl4b3z1pVVI,13591
+arionpay/errors.py,sha256=cpSd5wzMXaV0CsLyPl2lqTnANL01L3lmhM3FrgDYnQ4,833
+arionpay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arionpay/webhook.py,sha256=yuurjKZV0JL1RKYXoBo8rqXIK3bjEQmKUymXlGwsSRY,4752
+arionpay-1.0.0.dist-info/licenses/LICENSE,sha256=iTYJa9xSYji9gnfUFPbgMkWXuPplnVTDImYjDa8fweY,1065
+arionpay-1.0.0.dist-info/METADATA,sha256=SOvQVDp_DiW7GeZTkpLSyn4A5OFyF-jtx4TxpbSYtK8,8612
+arionpay-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+arionpay-1.0.0.dist-info/top_level.txt,sha256=JeHKLXdTui9JsIhOQeh9fwSjgYprlEtXS7GvAOp_ThI,9
+arionpay-1.0.0.dist-info/RECORD,,

arionpay-1.0.0.dist-info/WHEEL

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

arionpay-1.0.0.dist-info/licenses/LICENSE

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

arionpay-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+arionpay