qvard 0.1.0__tar.gz

qvard-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: qvard
+Version: 0.1.0
+Summary: Qvard payments API client for Python: payments, payouts, rates and webhook signature checks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# qvard (Python)
+
+Python client for the Qvard payments API. Zero dependencies (standard library only), Python 3.9 or newer.
+
+## Install
+
+```sh
+pip install qvard
+```
+
+## Quick start
+
+```python
+import os
+from qvard import Qvard
+
+qvard = Qvard(os.environ['QVARD_SECRET_KEY'])  # qvard_sk_...
+
+payment = qvard.payments.create(id='order-1001', price=10, currency='EUR')
+# send the payer to payment['redirectUrl']
+
+info = qvard.payments.get(payment['id'])
+print(info['status'])  # wait | partial | completed | rejected
+```
+
+Options: `Qvard(secret_key, base_url='https://api.qvard.com', timeout_ms=30000)`. `timeout_ms` is in milliseconds.
+
+## Keys
+
+- Use the secret key `qvard_sk_...` on your server only. Never put it in browser or mobile code. A publishable key (`qvard_pk_...`) is rejected by the constructor because it is for the browser only.
+- Legacy keys without the `qvard_sk_` prefix are rejected by the constructor. Rotate the key in the cabinet (Shop settings → API keys) to get a `qvard_sk_...` key.
+- The SDK sends `Authorization: Bearer <key>`. It never sends `x-api-key`.
+
+## Methods
+
+| Call | Request | Returns |
+| --- | --- | --- |
+| `payments.create(id=, price=, currency=None, payment_system_id=None)` | `POST /api/v1/payment` | `{id, redirectUrl, telegramUrl?}` |
+| `payments.get(id)` | `GET /api/v1/payment/:id` | `{id, status, createdAt, paidAt, price, currency, paidAmount, token, expiresAt}` |
+| `payouts.create(id=, price=, method_id=, address=, comment=None)` | `POST /api/v1/payout` | `True` |
+| `methods.info(id)` | `GET /api/v1/method/:id/info` | `{server, isReady, isActive}` |
+| `rates.list()` | `GET /api/v1/rates` | `{base, updatedAt, rates}` |
+
+The results are the server's `data` as dictionaries, with the server's field names (camelCase).
+
+- `id` in `payments.create` is your own order id. The server requires it. The same id with the same amount and currency returns the existing payment. A different amount replaces an unpaid one, and the server answers `409` once money is on the way.
+- `payments.get` answers `error.notfound` for a payment of another shop, the same as for an unknown uuid.
+- `price` is sent as you give it. The server converts it to USD at the current rate and stores that rate with the payment. Unset optional arguments (`None`) are not sent.
+- `convert_for_display(amount, from_, to, rates)` is exported for showing prices only. Pass `qvard.rates.list()['rates']`. The total a payer pays is computed by the server; do not charge the value this function returns. It raises `ValueError` for a currency without a rate.
+
+## Payouts
+
+`payouts.create` sends money out of your balance. Read this before you call it.
+
+- The SDK never retries a payout.
+- The result is **unknown** on a timeout, a network error, a `5xx` answer (including `502`, `503` and `504` from a gateway), or a `2xx` answer whose body is not a JSON object (an array, a string, `null` or an empty body). The error's `friendly_message` says: `Result unknown: check whether the payout went through before retrying (reuse the same id).`. A payout may have been created. In that case the error's `status` is the HTTP status and `message` is the server's key, or `HTTP <status>` when there is none.
+- A `4xx` answer is a refusal: the payout was not created, and `message` is the reason (for example `Insufficient balance`).
+- To retry safely, send the same `id` and the same arguments as the first attempt. See the next section.
+
+### Payout idempotency
+
+What protects a payout from being paid twice is the `id` field of the request body, which is your payout id.
+
+- The server requires `id`: without it the answer is `400`.
+- The server stores `id` on the withdrawal as its idempotency key. Before it creates a withdrawal it looks for an existing withdrawal of your shop with the same method and the same key. If it finds one, it returns that one and creates nothing.
+- The lookup runs under a database lock for your shop and method, so two simultaneous requests with the same `id` cannot both create a payout.
+- Scope: the key is matched within your shop and the `method_id`. The same `id` on a different method creates a second payout. The same `id` in a different shop is independent.
+- A repeated request with the same `id` returns the original payout, and the API answers `True` exactly as it does for a new payout. The response does not say that it was a replay.
+- A repeated request with the same `id` but a different `price`, `address` or `comment` is not compared. The original payout stands and the new values are ignored.
+- The lookup finds only payouts that were created. A request that was rejected with `400` (for example `Insufficient balance`) created nothing, so sending it again with the same `id` is a new attempt.
+- After a key rotation the previous key is not accepted on `POST /api/v1/payout`, even during the 24-hour grace period.
+- v1 has no endpoint to look up a payout by your id. To check whether a payout from a timed-out call exists, look in the cabinet.
+
+## Webhooks
+
+Qvard calls your callback URL with a JSON body and the header `X-Qvard-Signature: t=<unix>,v1=<hex>[,v1=<hex>]`. The signature is HMAC-SHA256, keyed with your secret key, over `t + "." + body`. Two `v1` values are sent for 24 hours after a key rotation, and either one is valid.
+
+Verify the signature over the **raw** body, before any JSON parsing. Read the body as bytes from your framework (not from a parsed form or JSON object):
+
+```python
+import os
+from qvard import Qvard
+
+secret = os.environ['QVARD_SECRET_KEY']
+qvard = Qvard(secret)
+
+def handle_webhook(raw_body: bytes, signature_header: str) -> int:
+    """Returns the HTTP status to answer with."""
+    try:
+        event = qvard.webhooks.construct_event(raw_body, signature_header, secret)
+    except ValueError:
+        return 400
+    # event['id'] is YOUR order id (the one you passed to payments.create), not the payment uuid.
+    # Check event['amount'] and event['currency'] against your order before you fulfil it.
+    return 200
+```
+
+- `qvard.webhooks.verify(raw_body, header, secret, tolerance_sec=300)` returns `True` or `False`. It raises `ValueError` only when no secret is given.
+- `qvard.webhooks.construct_event(raw_body, header, secret)` returns the parsed event, or raises `ValueError` when the signature fails.
+- `raw_body` may be `bytes` or `str`. The check accepts a timestamp within `tolerance_sec` (300 seconds) of now, in either direction, and accepts any `v1` that matches. The comparison is constant-time.
+- The event body is `{id, status, paymentLink?, customerEmail?, amount, currency, amountUsd, rate}`. There is no event `type` field.
+- Answer `200`. Qvard treats any other status as a failed delivery and retries it.
+
+## Errors
+
+Every failed call raises `QvardError`:
+
+- `status`: the HTTP status.
+- `message` (also `str(error)`): the server's key, for example `error.wrong.api.key`, or the text it sent.
+- `friendly_message`: an English explanation from the shared dictionary (`sdk/conformance/errors.json`, copied into the package). An unknown key is returned as is.
+- `errors`: for a rejected request body, a map from each field to its first message.
+- `request_id`: the server's `traceId`. Quote it to Qvard support.
+
+A request that got no answer (connection error, DNS, timeout) raises `QvardNetworkError`, a subclass of `QvardError` with `status` 0.
+
+```python
+from qvard import QvardError, QvardNetworkError
+
+try:
+    qvard.payments.get(uuid)
+except QvardNetworkError as e:
+    print('no answer:', e.friendly_message)
+except QvardError as e:
+    print(e.status, e.message, e.friendly_message, e.request_id)
+```
+
+| `message` | Status | Meaning |
+| --- | --- | --- |
+| `error.wrong.api.key` | 401 | Missing or unknown key |
+| `error.notfound` | 404 | Not in your shop |
+| `error.shop.not.active` | 403 | Shop is not active |
+| `error.origin.not_allowed` | 403 | Origin not in the allowed list (publishable-key flow only) |
+| `error.origin.not_configured` | 403 | No allowed origins configured (publishable-key flow only) |
+| `error.payment.duplicate_id` | 409 | Same id, but a different amount, or the payment is already paid |
+| `Error validation` | 400 | Body rejected; see `errors` |
+| `unsupported_currency` | 422 | Currency not supported |
+| `invalid_amount_precision` | 422 | Too many decimal places for the currency |
+| `rate_unavailable` | 422 | No rate for the currency right now |
+| `ThrottlerException: Too Many Requests` | 429 | Rate limit |
+| `error.internal` | 500 | Failure inside Qvard; quote `request_id` |
+
+Payout rejections come back as plain English text, for example `Insufficient balance`, `Method not found` or `Invalid TRON withdrawal address`, with status 400. The dictionary does not list them; `friendly_message` equals `message` for them.
+
+## Differences from the Node.js package
+
+- Redirects are not followed. A `3xx` answer is raised as a `QvardError`, so the secret key is never sent to another host. (`@qvard-sdk/node` does the same.)
+- `timeout_ms` bounds each socket operation (connecting, each read), not the whole request.
+
+## Tests
+
+No test dependencies. From `sdk/python`:
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+The tests read the shared fixtures from `../conformance`, so they run inside the `sdk/` folder.

qvard-0.1.0/README.md

@@ -0,0 +1,157 @@
+# qvard (Python)
+
+Python client for the Qvard payments API. Zero dependencies (standard library only), Python 3.9 or newer.
+
+## Install
+
+```sh
+pip install qvard
+```
+
+## Quick start
+
+```python
+import os
+from qvard import Qvard
+
+qvard = Qvard(os.environ['QVARD_SECRET_KEY'])  # qvard_sk_...
+
+payment = qvard.payments.create(id='order-1001', price=10, currency='EUR')
+# send the payer to payment['redirectUrl']
+
+info = qvard.payments.get(payment['id'])
+print(info['status'])  # wait | partial | completed | rejected
+```
+
+Options: `Qvard(secret_key, base_url='https://api.qvard.com', timeout_ms=30000)`. `timeout_ms` is in milliseconds.
+
+## Keys
+
+- Use the secret key `qvard_sk_...` on your server only. Never put it in browser or mobile code. A publishable key (`qvard_pk_...`) is rejected by the constructor because it is for the browser only.
+- Legacy keys without the `qvard_sk_` prefix are rejected by the constructor. Rotate the key in the cabinet (Shop settings → API keys) to get a `qvard_sk_...` key.
+- The SDK sends `Authorization: Bearer <key>`. It never sends `x-api-key`.
+
+## Methods
+
+| Call | Request | Returns |
+| --- | --- | --- |
+| `payments.create(id=, price=, currency=None, payment_system_id=None)` | `POST /api/v1/payment` | `{id, redirectUrl, telegramUrl?}` |
+| `payments.get(id)` | `GET /api/v1/payment/:id` | `{id, status, createdAt, paidAt, price, currency, paidAmount, token, expiresAt}` |
+| `payouts.create(id=, price=, method_id=, address=, comment=None)` | `POST /api/v1/payout` | `True` |
+| `methods.info(id)` | `GET /api/v1/method/:id/info` | `{server, isReady, isActive}` |
+| `rates.list()` | `GET /api/v1/rates` | `{base, updatedAt, rates}` |
+
+The results are the server's `data` as dictionaries, with the server's field names (camelCase).
+
+- `id` in `payments.create` is your own order id. The server requires it. The same id with the same amount and currency returns the existing payment. A different amount replaces an unpaid one, and the server answers `409` once money is on the way.
+- `payments.get` answers `error.notfound` for a payment of another shop, the same as for an unknown uuid.
+- `price` is sent as you give it. The server converts it to USD at the current rate and stores that rate with the payment. Unset optional arguments (`None`) are not sent.
+- `convert_for_display(amount, from_, to, rates)` is exported for showing prices only. Pass `qvard.rates.list()['rates']`. The total a payer pays is computed by the server; do not charge the value this function returns. It raises `ValueError` for a currency without a rate.
+
+## Payouts
+
+`payouts.create` sends money out of your balance. Read this before you call it.
+
+- The SDK never retries a payout.
+- The result is **unknown** on a timeout, a network error, a `5xx` answer (including `502`, `503` and `504` from a gateway), or a `2xx` answer whose body is not a JSON object (an array, a string, `null` or an empty body). The error's `friendly_message` says: `Result unknown: check whether the payout went through before retrying (reuse the same id).`. A payout may have been created. In that case the error's `status` is the HTTP status and `message` is the server's key, or `HTTP <status>` when there is none.
+- A `4xx` answer is a refusal: the payout was not created, and `message` is the reason (for example `Insufficient balance`).
+- To retry safely, send the same `id` and the same arguments as the first attempt. See the next section.
+
+### Payout idempotency
+
+What protects a payout from being paid twice is the `id` field of the request body, which is your payout id.
+
+- The server requires `id`: without it the answer is `400`.
+- The server stores `id` on the withdrawal as its idempotency key. Before it creates a withdrawal it looks for an existing withdrawal of your shop with the same method and the same key. If it finds one, it returns that one and creates nothing.
+- The lookup runs under a database lock for your shop and method, so two simultaneous requests with the same `id` cannot both create a payout.
+- Scope: the key is matched within your shop and the `method_id`. The same `id` on a different method creates a second payout. The same `id` in a different shop is independent.
+- A repeated request with the same `id` returns the original payout, and the API answers `True` exactly as it does for a new payout. The response does not say that it was a replay.
+- A repeated request with the same `id` but a different `price`, `address` or `comment` is not compared. The original payout stands and the new values are ignored.
+- The lookup finds only payouts that were created. A request that was rejected with `400` (for example `Insufficient balance`) created nothing, so sending it again with the same `id` is a new attempt.
+- After a key rotation the previous key is not accepted on `POST /api/v1/payout`, even during the 24-hour grace period.
+- v1 has no endpoint to look up a payout by your id. To check whether a payout from a timed-out call exists, look in the cabinet.
+
+## Webhooks
+
+Qvard calls your callback URL with a JSON body and the header `X-Qvard-Signature: t=<unix>,v1=<hex>[,v1=<hex>]`. The signature is HMAC-SHA256, keyed with your secret key, over `t + "." + body`. Two `v1` values are sent for 24 hours after a key rotation, and either one is valid.
+
+Verify the signature over the **raw** body, before any JSON parsing. Read the body as bytes from your framework (not from a parsed form or JSON object):
+
+```python
+import os
+from qvard import Qvard
+
+secret = os.environ['QVARD_SECRET_KEY']
+qvard = Qvard(secret)
+
+def handle_webhook(raw_body: bytes, signature_header: str) -> int:
+    """Returns the HTTP status to answer with."""
+    try:
+        event = qvard.webhooks.construct_event(raw_body, signature_header, secret)
+    except ValueError:
+        return 400
+    # event['id'] is YOUR order id (the one you passed to payments.create), not the payment uuid.
+    # Check event['amount'] and event['currency'] against your order before you fulfil it.
+    return 200
+```
+
+- `qvard.webhooks.verify(raw_body, header, secret, tolerance_sec=300)` returns `True` or `False`. It raises `ValueError` only when no secret is given.
+- `qvard.webhooks.construct_event(raw_body, header, secret)` returns the parsed event, or raises `ValueError` when the signature fails.
+- `raw_body` may be `bytes` or `str`. The check accepts a timestamp within `tolerance_sec` (300 seconds) of now, in either direction, and accepts any `v1` that matches. The comparison is constant-time.
+- The event body is `{id, status, paymentLink?, customerEmail?, amount, currency, amountUsd, rate}`. There is no event `type` field.
+- Answer `200`. Qvard treats any other status as a failed delivery and retries it.
+
+## Errors
+
+Every failed call raises `QvardError`:
+
+- `status`: the HTTP status.
+- `message` (also `str(error)`): the server's key, for example `error.wrong.api.key`, or the text it sent.
+- `friendly_message`: an English explanation from the shared dictionary (`sdk/conformance/errors.json`, copied into the package). An unknown key is returned as is.
+- `errors`: for a rejected request body, a map from each field to its first message.
+- `request_id`: the server's `traceId`. Quote it to Qvard support.
+
+A request that got no answer (connection error, DNS, timeout) raises `QvardNetworkError`, a subclass of `QvardError` with `status` 0.
+
+```python
+from qvard import QvardError, QvardNetworkError
+
+try:
+    qvard.payments.get(uuid)
+except QvardNetworkError as e:
+    print('no answer:', e.friendly_message)
+except QvardError as e:
+    print(e.status, e.message, e.friendly_message, e.request_id)
+```
+
+| `message` | Status | Meaning |
+| --- | --- | --- |
+| `error.wrong.api.key` | 401 | Missing or unknown key |
+| `error.notfound` | 404 | Not in your shop |
+| `error.shop.not.active` | 403 | Shop is not active |
+| `error.origin.not_allowed` | 403 | Origin not in the allowed list (publishable-key flow only) |
+| `error.origin.not_configured` | 403 | No allowed origins configured (publishable-key flow only) |
+| `error.payment.duplicate_id` | 409 | Same id, but a different amount, or the payment is already paid |
+| `Error validation` | 400 | Body rejected; see `errors` |
+| `unsupported_currency` | 422 | Currency not supported |
+| `invalid_amount_precision` | 422 | Too many decimal places for the currency |
+| `rate_unavailable` | 422 | No rate for the currency right now |
+| `ThrottlerException: Too Many Requests` | 429 | Rate limit |
+| `error.internal` | 500 | Failure inside Qvard; quote `request_id` |
+
+Payout rejections come back as plain English text, for example `Insufficient balance`, `Method not found` or `Invalid TRON withdrawal address`, with status 400. The dictionary does not list them; `friendly_message` equals `message` for them.
+
+## Differences from the Node.js package
+
+- Redirects are not followed. A `3xx` answer is raised as a `QvardError`, so the secret key is never sent to another host. (`@qvard-sdk/node` does the same.)
+- `timeout_ms` bounds each socket operation (connecting, each read), not the whole request.
+
+## Tests
+
+No test dependencies. From `sdk/python`:
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+The tests read the shared fixtures from `../conformance`, so they run inside the `sdk/` folder.

qvard-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qvard"
+version = "0.1.0"
+description = "Qvard payments API client for Python: payments, payouts, rates and webhook signature checks"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]

qvard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qvard-0.1.0/src/qvard/__init__.py

@@ -0,0 +1,137 @@
+"""Qvard payments API client. See README.md."""
+import http.client
+import json
+import socket
+import urllib.error
+import urllib.request
+from types import SimpleNamespace
+from typing import Any, Callable, Dict, Optional, Tuple
+from urllib.parse import quote
+
+from . import webhooks
+from .errors import PAYOUT_UNKNOWN_RESULT, QvardError, QvardNetworkError, error_from_response, network_error
+
+__all__ = ['Qvard', 'QvardError', 'QvardNetworkError', 'convert_for_display', 'webhooks']
+__version__ = '0.1.0'
+
+# A 3xx is an error here, not a hop: a redirect could send the Authorization header to another host.
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+def _urllib_send(method: str, url: str, headers: Dict[str, str], data: Optional[bytes],
+                 timeout_ms: int) -> Tuple[int, str]:
+    # shortcut: timeout_ms bounds each socket operation, not the whole request (Node bounds the whole request),
+    # upgrade to a total deadline if a server that trickles bytes becomes a real case
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with _OPENER.open(request, timeout=timeout_ms / 1000) as res:
+            return res.status, res.read().decode('utf-8', 'replace')
+    except urllib.error.HTTPError as e:
+        with e:
+            return e.code, e.read().decode('utf-8', 'replace')
+
+
+def _parse_json(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None  # a proxy's HTML page, an empty body
+
+
+class Qvard:
+    """Client for the payments API.
+
+    `secret_key` is your secret key, `qvard_sk_...`. Never put it in browser code: `qvard_pk_` is the public key.
+    Raises ValueError on an empty key, a `qvard_pk_` key, and a key without the `qvard_sk_` prefix.
+    `transport` replaces the HTTP layer (tests): called as (method, url, headers, body_bytes_or_None, timeout_ms),
+    returns (status, text), raises OSError on a network failure.
+    """
+
+    def __init__(self, secret_key: str, base_url: str = 'https://api.qvard.com', timeout_ms: int = 30000,
+                 transport: Optional[Callable[..., Tuple[int, str]]] = None):
+        if not secret_key:
+            raise ValueError('Qvard: secret key is required')
+        if secret_key.startswith('qvard_pk_'):
+            raise ValueError('Qvard: publishable key (qvard_pk_) is for the browser only; use the secret key (qvard_sk_) on the server')
+        if not secret_key.startswith('qvard_sk_'):
+            raise ValueError('Qvard: legacy keys without the qvard_sk_ prefix are not supported; rotate the key in the cabinet')
+
+        self._secret_key = secret_key
+        self._base_url = base_url.rstrip('/')
+        self._timeout_ms = timeout_ms
+        self._transport = transport or _urllib_send
+
+        # Only the listed fields are sent: `publishable_key` cannot reach the server from this client.
+        self.payments = SimpleNamespace(create=self._payment_create, get=self._payment_get)
+        self.payouts = SimpleNamespace(create=self._payout_create)
+        self.methods = SimpleNamespace(info=self._method_info)
+        self.rates = SimpleNamespace(list=self._rates_list)
+        # Webhook signature checks. Needs no network, only the shop secret key.
+        self.webhooks = webhooks
+
+    def _payment_create(self, id: str, price: float, currency: Optional[str] = None,
+                        payment_system_id: Optional[int] = None) -> Dict[str, Any]:
+        """Create a payment. Returns the uuid and the page to send the payer to."""
+        return self._request('POST', '/api/v1/payment', {
+            'id': id, 'price': price, 'currency': currency, 'paymentSystemId': payment_system_id,
+        })
+
+    def _payment_get(self, id: str) -> Dict[str, Any]:
+        """One payment of your shop, by the uuid that `create` returned. Another shop's payment is `error.notfound`."""
+        return self._request('GET', f'/api/v1/payment/{quote(str(id), safe="")}')
+
+    def _payout_create(self, id: str, price: float, method_id: int, address: str,
+                       comment: Optional[str] = None) -> Any:
+        """Send money out. Not retried automatically. On a timeout, a network error, a 5xx or an answer that is not JSON
+        the result is unknown: the `friendly_message` says so. Repeat only with the same `id` (see README)."""
+        return self._request('POST', '/api/v1/payout', {
+            'id': id, 'price': price, 'methodId': method_id, 'comment': comment, 'address': address,
+        }, payout=True)
+
+    def _method_info(self, id: int) -> Dict[str, Any]:
+        """Status of a payment method of your shop, by its id from the cabinet."""
+        return self._request('GET', f'/api/v1/method/{quote(str(id), safe="")}/info')
+
+    def _rates_list(self) -> Dict[str, Any]:
+        """Current rates, for display only: the server computes the amount a payment costs."""
+        return self._request('GET', '/api/v1/rates')
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None, payout: bool = False) -> Any:
+        headers = {'Authorization': f'Bearer {self._secret_key}', 'Content-Type': 'application/json'}
+        data = None
+        if body is not None:
+            data = json.dumps({k: v for k, v in body.items() if v is not None}).encode('utf-8')
+        try:
+            status, text = self._transport(method, self._base_url + path, headers, data, self._timeout_ms)
+        except (OSError, http.client.HTTPException) as e:
+            raise network_error(e, isinstance(getattr(e, 'reason', e), socket.timeout), payout) from e
+
+        parsed = _parse_json(text)
+        if payout and (status >= 500 or (200 <= status <= 299 and not isinstance(parsed, dict))):
+            # The answer is lost or unreadable: the payout may have been created.
+            err = error_from_response(status, parsed)
+            raise QvardError(status, err.message, err.errors, err.request_id, PAYOUT_UNKNOWN_RESULT)
+        if not 200 <= status <= 299:
+            raise error_from_response(status, parsed)
+
+        return parsed.get('data') if isinstance(parsed, dict) else None
+
+
+def convert_for_display(amount: float, from_: str, to: str, rates: Dict[str, float]) -> float:
+    """Display only: converts `amount` between two currencies with the rates from `rates.list()` (units per 1 USD).
+    The server computes the amount a payment actually costs; do not charge this number.
+    Raises ValueError when a currency has no rate (USD is always 1)."""
+    def per_usd(code: str) -> Optional[float]:
+        return 1 if code == 'USD' else rates.get(code)
+
+    from_rate = per_usd(from_)
+    to_rate = per_usd(to)
+    if not from_rate or not to_rate:
+        raise ValueError(f"Qvard: no rate for {to if from_rate else from_}")
+
+    return (amount / from_rate) * to_rate

qvard-0.1.0/src/qvard/errors.py

@@ -0,0 +1,67 @@
+"""Errors and the friendly-message dictionary. The dictionary is a copy of sdk/conformance/errors.json:
+the package ships without that folder, and tests/test_qvard.py fails if the two drift apart."""
+from typing import Any, Dict, Optional
+
+ERROR_MESSAGES: Dict[str, str] = {
+    'error.wrong.api.key': 'Invalid or missing API key',
+    'error.notfound': 'Not found in your shop',
+    'error.shop.not.active': 'Shop is not active',
+    'error.payment.duplicate_id': 'A payment with this id already exists and cannot be replaced (different amount, or already paid)',
+    'error.origin.not_allowed': "Request origin is not in the shop's allowed list",
+    'error.origin.not_configured': 'The shop has no allowed origins configured for this key',
+    'error.internal': "Internal error on Qvard's side; quote traceId to support",
+    'Error validation': 'Request validation failed; see errors for each field',
+    'unsupported_currency': 'Currency is not supported',
+    'invalid_amount_precision': 'Amount has more decimal places than this currency allows',
+    'rate_unavailable': 'No exchange rate is available for this currency right now',
+    'ThrottlerException: Too Many Requests': 'Too many requests, retry later',
+}
+
+# Shown instead of the generic network text for payouts: the money may already have moved.
+PAYOUT_UNKNOWN_RESULT = 'Result unknown: check whether the payout went through before retrying (reuse the same id).'
+
+
+class QvardError(Exception):
+    """An answer from the server. `message` is the raw key (`error.*`) or text, as the server sent it."""
+
+    def __init__(self, status: int, message: str, errors: Optional[Any] = None,
+                 request_id: Optional[str] = None, friendly_message: Optional[str] = None):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.errors = errors
+        # The server's `traceId`; quote it to Qvard support.
+        self.request_id = request_id
+        self.friendly_message = ERROR_MESSAGES.get(message, message) if friendly_message is None else friendly_message
+
+
+class QvardNetworkError(QvardError):
+    """No answer arrived (DNS, connection, TLS) or the request timed out. `status` is 0."""
+
+    def __init__(self, message: str, friendly_message: str):
+        super().__init__(0, message, None, None, friendly_message)
+
+
+def error_from_response(status: int, body: Any) -> QvardError:
+    json_body = body if isinstance(body, dict) else {}
+    message = json_body.get('message')
+    errors = json_body.get('errors')
+    request_id = json_body.get('traceId')
+
+    return QvardError(
+        status,
+        message if isinstance(message, str) else f'HTTP {status}',
+        errors if isinstance(errors, (dict, list)) else None,
+        request_id if isinstance(request_id, str) else None,
+    )
+
+
+def network_error(cause: BaseException, timed_out: bool, payout: bool) -> QvardNetworkError:
+    if timed_out:
+        plain = 'Request timed out'
+        message = 'timeout'
+    else:
+        plain = 'Network error'
+        message = f'network: {cause}'
+
+    return QvardNetworkError(message, PAYOUT_UNKNOWN_RESULT if payout else plain)

qvard-0.1.0/src/qvard/webhooks.py

@@ -0,0 +1,51 @@
+"""Checks `X-Qvard-Signature: t=<unix>,v1=<hex>[,v1=<hex>]`: HMAC-SHA256 with the shop's secret key over `t + "." + rawBody`.
+Pass the RAW body (bytes or str, as received), not re-serialised JSON."""
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Optional, Union
+
+
+def verify(raw_body: Union[str, bytes], header: Optional[str], secret: str,
+           tolerance_sec: int = 300, now: Optional[int] = None) -> bool:
+    """Returns False for a bad, missing or stale signature; raises ValueError only when no secret is given.
+    `tolerance_sec` bounds |now - t| in both directions. Any `v1` may match (two while a key rotation is live).
+    `now` (unix seconds) overrides the clock; for tests."""
+    if not secret:
+        raise ValueError('Qvard: webhook secret is required')
+
+    t = None
+    v1 = []
+    for part in (header or '').split(','):
+        key, *rest = part.split('=')
+        value = '='.join(rest).strip()
+        if key.strip() == 't' and t is None:
+            t = value
+        elif key.strip() == 'v1':
+            v1.append(value)
+    if not t or not re.fullmatch(r'[0-9]+', t):
+        return False
+    if abs((int(time.time()) if now is None else now) - int(t)) > tolerance_sec:
+        return False
+
+    expected = hmac.new(secret.encode('utf-8'), t.encode('ascii') + b'.' + _bytes(raw_body), hashlib.sha256).hexdigest()
+
+    return any(
+        re.fullmatch(r'[0-9a-fA-F]{64}', hex_sig) is not None and hmac.compare_digest(expected, hex_sig.lower())
+        for hex_sig in v1
+    )
+
+
+def construct_event(raw_body: Union[str, bytes], header: Optional[str], secret: str,
+                    now: Optional[int] = None) -> Any:
+    """Verifies, then parses the raw body. Raises ValueError when the signature does not verify."""
+    if not verify(raw_body, header, secret, now=now):
+        raise ValueError('Qvard: invalid webhook signature, or timestamp outside the tolerance')
+
+    return json.loads(_bytes(raw_body).decode('utf-8'))
+
+
+def _bytes(raw_body: Union[str, bytes]) -> bytes:
+    return raw_body.encode('utf-8') if isinstance(raw_body, str) else raw_body

qvard-0.1.0/src/qvard.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: qvard
+Version: 0.1.0
+Summary: Qvard payments API client for Python: payments, payouts, rates and webhook signature checks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# qvard (Python)
+
+Python client for the Qvard payments API. Zero dependencies (standard library only), Python 3.9 or newer.
+
+## Install
+
+```sh
+pip install qvard
+```
+
+## Quick start
+
+```python
+import os
+from qvard import Qvard
+
+qvard = Qvard(os.environ['QVARD_SECRET_KEY'])  # qvard_sk_...
+
+payment = qvard.payments.create(id='order-1001', price=10, currency='EUR')
+# send the payer to payment['redirectUrl']
+
+info = qvard.payments.get(payment['id'])
+print(info['status'])  # wait | partial | completed | rejected
+```
+
+Options: `Qvard(secret_key, base_url='https://api.qvard.com', timeout_ms=30000)`. `timeout_ms` is in milliseconds.
+
+## Keys
+
+- Use the secret key `qvard_sk_...` on your server only. Never put it in browser or mobile code. A publishable key (`qvard_pk_...`) is rejected by the constructor because it is for the browser only.
+- Legacy keys without the `qvard_sk_` prefix are rejected by the constructor. Rotate the key in the cabinet (Shop settings → API keys) to get a `qvard_sk_...` key.
+- The SDK sends `Authorization: Bearer <key>`. It never sends `x-api-key`.
+
+## Methods
+
+| Call | Request | Returns |
+| --- | --- | --- |
+| `payments.create(id=, price=, currency=None, payment_system_id=None)` | `POST /api/v1/payment` | `{id, redirectUrl, telegramUrl?}` |
+| `payments.get(id)` | `GET /api/v1/payment/:id` | `{id, status, createdAt, paidAt, price, currency, paidAmount, token, expiresAt}` |
+| `payouts.create(id=, price=, method_id=, address=, comment=None)` | `POST /api/v1/payout` | `True` |
+| `methods.info(id)` | `GET /api/v1/method/:id/info` | `{server, isReady, isActive}` |
+| `rates.list()` | `GET /api/v1/rates` | `{base, updatedAt, rates}` |
+
+The results are the server's `data` as dictionaries, with the server's field names (camelCase).
+
+- `id` in `payments.create` is your own order id. The server requires it. The same id with the same amount and currency returns the existing payment. A different amount replaces an unpaid one, and the server answers `409` once money is on the way.
+- `payments.get` answers `error.notfound` for a payment of another shop, the same as for an unknown uuid.
+- `price` is sent as you give it. The server converts it to USD at the current rate and stores that rate with the payment. Unset optional arguments (`None`) are not sent.
+- `convert_for_display(amount, from_, to, rates)` is exported for showing prices only. Pass `qvard.rates.list()['rates']`. The total a payer pays is computed by the server; do not charge the value this function returns. It raises `ValueError` for a currency without a rate.
+
+## Payouts
+
+`payouts.create` sends money out of your balance. Read this before you call it.
+
+- The SDK never retries a payout.
+- The result is **unknown** on a timeout, a network error, a `5xx` answer (including `502`, `503` and `504` from a gateway), or a `2xx` answer whose body is not a JSON object (an array, a string, `null` or an empty body). The error's `friendly_message` says: `Result unknown: check whether the payout went through before retrying (reuse the same id).`. A payout may have been created. In that case the error's `status` is the HTTP status and `message` is the server's key, or `HTTP <status>` when there is none.
+- A `4xx` answer is a refusal: the payout was not created, and `message` is the reason (for example `Insufficient balance`).
+- To retry safely, send the same `id` and the same arguments as the first attempt. See the next section.
+
+### Payout idempotency
+
+What protects a payout from being paid twice is the `id` field of the request body, which is your payout id.
+
+- The server requires `id`: without it the answer is `400`.
+- The server stores `id` on the withdrawal as its idempotency key. Before it creates a withdrawal it looks for an existing withdrawal of your shop with the same method and the same key. If it finds one, it returns that one and creates nothing.
+- The lookup runs under a database lock for your shop and method, so two simultaneous requests with the same `id` cannot both create a payout.
+- Scope: the key is matched within your shop and the `method_id`. The same `id` on a different method creates a second payout. The same `id` in a different shop is independent.
+- A repeated request with the same `id` returns the original payout, and the API answers `True` exactly as it does for a new payout. The response does not say that it was a replay.
+- A repeated request with the same `id` but a different `price`, `address` or `comment` is not compared. The original payout stands and the new values are ignored.
+- The lookup finds only payouts that were created. A request that was rejected with `400` (for example `Insufficient balance`) created nothing, so sending it again with the same `id` is a new attempt.
+- After a key rotation the previous key is not accepted on `POST /api/v1/payout`, even during the 24-hour grace period.
+- v1 has no endpoint to look up a payout by your id. To check whether a payout from a timed-out call exists, look in the cabinet.
+
+## Webhooks
+
+Qvard calls your callback URL with a JSON body and the header `X-Qvard-Signature: t=<unix>,v1=<hex>[,v1=<hex>]`. The signature is HMAC-SHA256, keyed with your secret key, over `t + "." + body`. Two `v1` values are sent for 24 hours after a key rotation, and either one is valid.
+
+Verify the signature over the **raw** body, before any JSON parsing. Read the body as bytes from your framework (not from a parsed form or JSON object):
+
+```python
+import os
+from qvard import Qvard
+
+secret = os.environ['QVARD_SECRET_KEY']
+qvard = Qvard(secret)
+
+def handle_webhook(raw_body: bytes, signature_header: str) -> int:
+    """Returns the HTTP status to answer with."""
+    try:
+        event = qvard.webhooks.construct_event(raw_body, signature_header, secret)
+    except ValueError:
+        return 400
+    # event['id'] is YOUR order id (the one you passed to payments.create), not the payment uuid.
+    # Check event['amount'] and event['currency'] against your order before you fulfil it.
+    return 200
+```
+
+- `qvard.webhooks.verify(raw_body, header, secret, tolerance_sec=300)` returns `True` or `False`. It raises `ValueError` only when no secret is given.
+- `qvard.webhooks.construct_event(raw_body, header, secret)` returns the parsed event, or raises `ValueError` when the signature fails.
+- `raw_body` may be `bytes` or `str`. The check accepts a timestamp within `tolerance_sec` (300 seconds) of now, in either direction, and accepts any `v1` that matches. The comparison is constant-time.
+- The event body is `{id, status, paymentLink?, customerEmail?, amount, currency, amountUsd, rate}`. There is no event `type` field.
+- Answer `200`. Qvard treats any other status as a failed delivery and retries it.
+
+## Errors
+
+Every failed call raises `QvardError`:
+
+- `status`: the HTTP status.
+- `message` (also `str(error)`): the server's key, for example `error.wrong.api.key`, or the text it sent.
+- `friendly_message`: an English explanation from the shared dictionary (`sdk/conformance/errors.json`, copied into the package). An unknown key is returned as is.
+- `errors`: for a rejected request body, a map from each field to its first message.
+- `request_id`: the server's `traceId`. Quote it to Qvard support.
+
+A request that got no answer (connection error, DNS, timeout) raises `QvardNetworkError`, a subclass of `QvardError` with `status` 0.
+
+```python
+from qvard import QvardError, QvardNetworkError
+
+try:
+    qvard.payments.get(uuid)
+except QvardNetworkError as e:
+    print('no answer:', e.friendly_message)
+except QvardError as e:
+    print(e.status, e.message, e.friendly_message, e.request_id)
+```
+
+| `message` | Status | Meaning |
+| --- | --- | --- |
+| `error.wrong.api.key` | 401 | Missing or unknown key |
+| `error.notfound` | 404 | Not in your shop |
+| `error.shop.not.active` | 403 | Shop is not active |
+| `error.origin.not_allowed` | 403 | Origin not in the allowed list (publishable-key flow only) |
+| `error.origin.not_configured` | 403 | No allowed origins configured (publishable-key flow only) |
+| `error.payment.duplicate_id` | 409 | Same id, but a different amount, or the payment is already paid |
+| `Error validation` | 400 | Body rejected; see `errors` |
+| `unsupported_currency` | 422 | Currency not supported |
+| `invalid_amount_precision` | 422 | Too many decimal places for the currency |
+| `rate_unavailable` | 422 | No rate for the currency right now |
+| `ThrottlerException: Too Many Requests` | 429 | Rate limit |
+| `error.internal` | 500 | Failure inside Qvard; quote `request_id` |
+
+Payout rejections come back as plain English text, for example `Insufficient balance`, `Method not found` or `Invalid TRON withdrawal address`, with status 400. The dictionary does not list them; `friendly_message` equals `message` for them.
+
+## Differences from the Node.js package
+
+- Redirects are not followed. A `3xx` answer is raised as a `QvardError`, so the secret key is never sent to another host. (`@qvard-sdk/node` does the same.)
+- `timeout_ms` bounds each socket operation (connecting, each read), not the whole request.
+
+## Tests
+
+No test dependencies. From `sdk/python`:
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+The tests read the shared fixtures from `../conformance`, so they run inside the `sdk/` folder.

qvard-0.1.0/src/qvard.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/qvard/__init__.py
+src/qvard/errors.py
+src/qvard/webhooks.py
+src/qvard.egg-info/PKG-INFO
+src/qvard.egg-info/SOURCES.txt
+src/qvard.egg-info/dependency_links.txt
+src/qvard.egg-info/top_level.txt
+tests/test_qvard.py
+tests/test_webhooks.py

qvard-0.1.0/src/qvard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qvard-0.1.0/src/qvard.egg-info/top_level.txt

@@ -0,0 +1 @@
+qvard

qvard-0.1.0/tests/test_qvard.py

@@ -0,0 +1,275 @@
+"""Client tests. Run from sdk/python: PYTHONPATH=src python3 -m unittest discover -s tests -v
+Fixtures are read from ../conformance (shared with every SDK)."""
+import json
+import socket
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from qvard import Qvard, QvardError, QvardNetworkError, convert_for_display
+from qvard.errors import ERROR_MESSAGES, PAYOUT_UNKNOWN_RESULT
+
+ROOT = Path(__file__).resolve().parents[2]  # sdk/
+KEY = 'qvard_sk_test123'
+BASE = 'https://api.qvard.com'
+
+
+def fixture(path):
+    return json.loads((ROOT / 'conformance' / path).read_text(encoding='utf-8'))
+
+
+class Recorder:
+    """Transport stub: records each call and answers with a fixed status and body (or raises)."""
+
+    def __init__(self, status=200, body='', error=None):
+        self.status = status
+        self.body = body if isinstance(body, str) else json.dumps(body)
+        self.error = error
+        self.calls = []
+
+    def __call__(self, method, url, headers, data, timeout_ms):
+        self.calls.append({'method': method, 'url': url, 'headers': headers, 'data': data, 'timeout_ms': timeout_ms})
+        if self.error is not None:
+            raise self.error
+        return self.status, self.body
+
+    def sent_json(self):
+        return json.loads(self.calls[0]['data'])
+
+
+class ConstructorTests(unittest.TestCase):
+    def test_rejects_empty_key(self):
+        with self.assertRaisesRegex(ValueError, 'secret key is required'):
+            Qvard('')
+
+    def test_rejects_publishable_key(self):
+        with self.assertRaisesRegex(ValueError, 'publishable key \\(qvard_pk_\\) is for the browser only'):
+            Qvard('qvard_pk_abc')
+
+    def test_rejects_legacy_key(self):
+        with self.assertRaisesRegex(ValueError, 'legacy keys without the qvard_sk_ prefix are not supported'):
+            Qvard('legacy-token-123')
+
+    def test_accepts_secret_key(self):
+        self.assertIsInstance(Qvard(KEY), Qvard)
+
+
+class RequestShapeTests(unittest.TestCase):
+    def test_sends_bearer_and_never_x_api_key(self):
+        t = Recorder(200, fixture('responses/rates.json'))
+        Qvard(KEY, transport=t).rates.list()
+        headers = t.calls[0]['headers']
+        self.assertEqual(headers['Authorization'], f'Bearer {KEY}')
+        self.assertFalse(any(k.lower() == 'x-api-key' for k in headers))
+
+    def test_base_url_replaces_default_and_loses_trailing_slashes(self):
+        t = Recorder(200, fixture('responses/rates.json'))
+        Qvard(KEY, base_url='http://localhost:9999/', transport=t).rates.list()
+        self.assertEqual(t.calls[0]['url'], 'http://localhost:9999/api/v1/rates')
+
+    def test_default_timeout_is_30_seconds(self):
+        t = Recorder(200, fixture('responses/rates.json'))
+        Qvard(KEY, transport=t).rates.list()
+        self.assertEqual(t.calls[0]['timeout_ms'], 30000)
+
+
+class MethodTests(unittest.TestCase):
+    def test_payments_create_posts_the_fields_and_unwraps_data(self):
+        t = Recorder(201, fixture('responses/payment-create.json'))
+        result = Qvard(KEY, transport=t).payments.create(id='order-1', price=10.5, currency='EUR', payment_system_id=3)
+        self.assertEqual(t.calls[0]['url'], f'{BASE}/api/v1/payment')
+        self.assertEqual(t.calls[0]['method'], 'POST')
+        self.assertEqual(t.sent_json(), {'id': 'order-1', 'price': 10.5, 'currency': 'EUR', 'paymentSystemId': 3})
+        self.assertEqual(result, fixture('responses/payment-create.json')['data'])
+
+    def test_payments_create_omits_unset_fields(self):
+        t = Recorder(201, fixture('responses/payment-create.json'))
+        Qvard(KEY, transport=t).payments.create(id='x', price=0)
+        self.assertEqual(t.sent_json(), {'id': 'x', 'price': 0})
+
+    def test_payments_create_cannot_forward_publishable_key(self):
+        t = Recorder(201, fixture('responses/payment-create.json'))
+        with self.assertRaises(TypeError):
+            Qvard(KEY, transport=t).payments.create(id='x', price=1, publishable_key='qvard_pk_leak')
+        self.assertEqual(t.calls, [])
+
+    def test_payments_get_reads_one_payment_by_uuid_and_unwraps_data(self):
+        t = Recorder(200, fixture('responses/payment-get.json'))
+        result = Qvard(KEY, transport=t).payments.get('a1b2c3d4-0000-4000-8000-000000000007')
+        self.assertEqual(t.calls[0]['url'], f'{BASE}/api/v1/payment/a1b2c3d4-0000-4000-8000-000000000007')
+        self.assertEqual(t.calls[0]['method'], 'GET')
+        self.assertIsNone(t.calls[0]['data'])
+        self.assertEqual(result, fixture('responses/payment-get.json')['data'])
+
+    def test_payouts_create_posts_the_payout_and_returns_true(self):
+        t = Recorder(201, fixture('responses/payout-create.json'))
+        result = Qvard(KEY, transport=t).payouts.create(id='payout-1', price=150, method_id=4, address='TXpAy', comment='weekly')
+        self.assertEqual(t.calls[0]['url'], f'{BASE}/api/v1/payout')
+        self.assertEqual(t.sent_json(), {'id': 'payout-1', 'price': 150, 'methodId': 4, 'address': 'TXpAy', 'comment': 'weekly'})
+        self.assertIs(result, True)
+
+    def test_methods_info_reads_method_and_unwraps_data(self):
+        t = Recorder(200, fixture('responses/method-info.json'))
+        result = Qvard(KEY, transport=t).methods.info(7)
+        self.assertEqual(t.calls[0]['url'], f'{BASE}/api/v1/method/7/info')
+        self.assertEqual(result, fixture('responses/method-info.json')['data'])
+
+    def test_rates_list_reads_rates_and_unwraps_data(self):
+        t = Recorder(200, fixture('responses/rates.json'))
+        result = Qvard(KEY, transport=t).rates.list()
+        self.assertEqual(t.calls[0]['url'], f'{BASE}/api/v1/rates')
+        self.assertEqual(result, fixture('responses/rates.json')['data'])
+
+
+class ConvertForDisplayTests(unittest.TestCase):
+    RATES = {'EUR': 0.92, 'INR': 83.1}
+
+    def test_converts_through_usd_in_both_directions(self):
+        self.assertAlmostEqual(convert_for_display(100, 'EUR', 'USD', self.RATES), 100 / 0.92, places=9)
+        self.assertAlmostEqual(convert_for_display(10, 'USD', 'EUR', self.RATES), 9.2, places=9)
+        self.assertAlmostEqual(convert_for_display(1, 'EUR', 'INR', self.RATES), 83.1 / 0.92, places=9)
+
+    def test_raises_for_a_currency_without_a_rate(self):
+        with self.assertRaisesRegex(ValueError, 'no rate for GBP'):
+            convert_for_display(1, 'GBP', 'USD', self.RATES)
+        with self.assertRaisesRegex(ValueError, 'no rate for constructor'):
+            convert_for_display(1, 'USD', 'constructor', self.RATES)
+
+
+class ErrorMappingTests(unittest.TestCase):
+    def test_each_error_fixture_maps_to_qvard_error(self):
+        for case in fixture('error-responses.json'):
+            with self.subTest(case=case['name']):
+                t = Recorder(case['status'], case['body'])
+                with self.assertRaises(QvardError) as ctx:
+                    Qvard(KEY, transport=t).payments.get('x')
+                err = ctx.exception
+                self.assertEqual(err.status, case['status'])
+                self.assertEqual(err.message, case['expected']['message'])
+                self.assertEqual(err.friendly_message, case['expected']['friendlyMessage'])
+                self.assertEqual(err.request_id, case['expected'].get('requestId'))
+                self.assertEqual(err.errors, case['expected'].get('errors'))
+
+    def test_non_json_error_body_does_not_crash(self):
+        t = Recorder(502, '<html>Bad Gateway</html>')
+        with self.assertRaises(QvardError) as ctx:
+            Qvard(KEY, transport=t).rates.list()
+        self.assertEqual(ctx.exception.status, 502)
+        self.assertEqual(ctx.exception.message, 'HTTP 502')
+        self.assertIsNone(ctx.exception.request_id)
+
+    def test_friendly_dictionary_is_the_shared_errors_json(self):
+        self.assertEqual(ERROR_MESSAGES, fixture('errors.json'))
+
+
+class NetworkTests(unittest.TestCase):
+    def test_connection_error_becomes_network_error_without_retry(self):
+        t = Recorder(error=OSError('connection refused'))
+        with self.assertRaises(QvardNetworkError) as ctx:
+            Qvard(KEY, transport=t).payments.get('x')
+        self.assertEqual(ctx.exception.status, 0)
+        self.assertEqual(ctx.exception.friendly_message, 'Network error')
+        self.assertEqual(len(t.calls), 1)
+
+    def test_timeout_becomes_network_error_and_payouts_get_the_unknown_result_warning(self):
+        t = Recorder(error=socket.timeout('timed out'))
+        client = Qvard(KEY, transport=t)
+        with self.assertRaises(QvardNetworkError) as ctx:
+            client.payouts.create(id='p', price=1, method_id=1, address='a')
+        self.assertEqual(ctx.exception.friendly_message, PAYOUT_UNKNOWN_RESULT)
+        self.assertEqual(len(t.calls), 1)
+
+        with self.assertRaises(QvardNetworkError) as ctx:
+            client.payments.create(id='x', price=1)
+        self.assertEqual(ctx.exception.friendly_message, 'Request timed out')
+
+
+class PayoutUnknownResultTests(unittest.TestCase):
+    def test_each_payout_fixture_maps_to_qvard_error(self):
+        for case in fixture('payout-unknown.json'):
+            with self.subTest(case=case['name']):
+                t = Recorder(case['status'], case['body'])
+                with self.assertRaises(QvardError) as ctx:
+                    Qvard(KEY, transport=t).payouts.create(id='p', price=1, method_id=1, address='a')
+                err = ctx.exception
+                self.assertEqual(err.status, case['status'])
+                self.assertEqual(err.message, case['expected']['message'])
+                self.assertEqual(err.friendly_message, case['expected']['friendlyMessage'])
+                self.assertEqual(err.request_id, case['expected'].get('requestId'))
+
+    def test_502_on_payments_create_is_a_plain_error(self):
+        t = Recorder(502, '<html>Bad Gateway</html>')
+        with self.assertRaises(QvardError) as ctx:
+            Qvard(KEY, transport=t).payments.create(id='x', price=1)
+        self.assertEqual(ctx.exception.friendly_message, 'HTTP 502')
+
+
+class LocalServerTests(unittest.TestCase):
+    """Runs the default urllib transport against a real local socket: headers, redirects, timeout."""
+
+    @classmethod
+    def setUpClass(cls):
+        hits = []
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *args):
+                pass
+
+            def _answer(self, status, body, extra=None):
+                payload = json.dumps(body).encode('utf-8')
+                self.send_response(status)
+                for k, v in (extra or {}).items():
+                    self.send_header(k, v)
+                self.send_header('Content-Type', 'application/json')
+                self.send_header('Content-Length', str(len(payload)))
+                self.end_headers()
+                self.wfile.write(payload)
+
+            def do_GET(self):
+                hits.append((self.path, self.headers.get('Authorization')))
+                if self.path == '/api/v1/payment/slow':
+                    time.sleep(1)
+                    return self._answer(200, {'data': None})
+                self._answer(200, fixture('responses/rates.json'))
+
+            def do_POST(self):
+                hits.append((self.path, self.headers.get('Authorization')))
+                self.rfile.read(int(self.headers.get('Content-Length', 0)))
+                # A redirect must not be followed: the Authorization header would go to the Location host.
+                self._answer(302, {}, {'Location': 'http://127.0.0.1:1/elsewhere'})
+
+        cls.hits = hits
+        cls.server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
+        cls.server.daemon_threads = True
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+        cls.url = f'http://127.0.0.1:{cls.server.server_address[1]}'
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def test_real_request_sends_bearer_and_unwraps_data(self):
+        self.hits.clear()
+        result = Qvard(KEY, base_url=self.url).rates.list()
+        self.assertEqual(result, fixture('responses/rates.json')['data'])
+        self.assertEqual(self.hits[-1], ('/api/v1/rates', f'Bearer {KEY}'))
+
+    def test_redirect_is_an_error_and_is_not_followed(self):
+        self.hits.clear()
+        with self.assertRaises(QvardError) as ctx:
+            Qvard(KEY, base_url=self.url).payouts.create(id='p', price=1, method_id=1, address='a')
+        self.assertEqual(ctx.exception.status, 302)
+        self.assertEqual(len(self.hits), 1)
+
+    def test_slow_server_times_out(self):
+        with self.assertRaises(QvardNetworkError) as ctx:
+            Qvard(KEY, base_url=self.url, timeout_ms=100).payments.get('slow')
+        self.assertEqual(ctx.exception.friendly_message, 'Request timed out')
+
+
+if __name__ == '__main__':
+    unittest.main()

qvard-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,54 @@
+"""Webhook signature tests over the shared vectors in ../conformance/webhook-vectors.json."""
+import json
+import unittest
+from pathlib import Path
+
+from qvard import Qvard, webhooks
+
+ROOT = Path(__file__).resolve().parents[2]  # sdk/
+VECTORS = json.loads((ROOT / 'conformance' / 'webhook-vectors.json').read_text(encoding='utf-8'))
+KEY = 'qvard_sk_test123'
+
+
+class WebhookTests(unittest.TestCase):
+    def test_every_vector(self):
+        for case in VECTORS['cases']:
+            with self.subTest(case=case['name']):
+                body = case.get('rawBody', VECTORS['rawBody'])
+                self.assertIs(
+                    webhooks.verify(body, case['header'], VECTORS['secret'], now=VECTORS['now']),
+                    case['expected'],
+                )
+
+    def test_uppercase_hex_of_a_valid_signature_is_accepted(self):
+        valid = next(c for c in VECTORS['cases'] if c['expected'] is True and 'rawBody' not in c)
+        t, v1 = valid['header'].split(',', 1)
+        self.assertTrue(webhooks.verify(VECTORS['rawBody'], f"{t},{v1[:3]}{v1[3:].upper()}", VECTORS['secret'], now=VECTORS['now']))
+
+    def test_construct_event_returns_parsed_event_for_valid_signature(self):
+        valid = next(c for c in VECTORS['cases'] if c['expected'] is True and 'rawBody' not in c)
+        event = webhooks.construct_event(VECTORS['rawBody'], valid['header'], VECTORS['secret'], now=VECTORS['now'])
+        self.assertEqual(event, json.loads(VECTORS['rawBody']))
+        self.assertEqual(event['id'], 'ext-42')
+
+    def test_construct_event_raises_for_bad_signature(self):
+        bad = next(c for c in VECTORS['cases'] if c['expected'] is False)
+        with self.assertRaisesRegex(ValueError, 'invalid webhook signature'):
+            webhooks.construct_event(VECTORS['rawBody'], bad['header'], VECTORS['secret'], now=VECTORS['now'])
+
+    def test_bytes_body_and_wider_tolerance(self):
+        old = next(c for c in VECTORS['cases'] if c['name'].startswith('t 301 seconds old'))
+        raw = VECTORS['rawBody'].encode('utf-8')
+        self.assertFalse(webhooks.verify(raw, old['header'], VECTORS['secret'], now=VECTORS['now']))
+        self.assertTrue(webhooks.verify(raw, old['header'], VECTORS['secret'], tolerance_sec=600, now=VECTORS['now']))
+
+    def test_verify_raises_when_no_secret_is_given(self):
+        with self.assertRaisesRegex(ValueError, 'webhook secret is required'):
+            webhooks.verify(VECTORS['rawBody'], 't=1,v1=00', '')
+
+    def test_client_exposes_the_same_functions(self):
+        self.assertIs(Qvard(KEY).webhooks.verify, webhooks.verify)
+
+
+if __name__ == '__main__':
+    unittest.main()