epoint-python-sdk 0.2.0__tar.gz

epoint_python_sdk-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

epoint_python_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0
+
+- Apple Pay and Google Pay: `widgets.create` returns `Widget.origin` for `postMessage` checks, `widgets.split` covers `token/split-payment`
+- `WidgetMessage.from_event` reads the widget `postMessage` as an untrusted hint
+- `Transaction.matches(order_id, amount, transaction)` for callback cross checks
+- Signed requests are refused over plain http outside localhost unless `allow_insecure_http` is set
+- Callback `data` over 64 KB and signatures over 128 characters are rejected before hashing
+
+## 0.1.0
+
+- Sync `Epoint` and async `AsyncEpoint`
+- Payments, saved cards, payouts, split, pre-auth, installments, wallets, Apple Pay and Google Pay widget, invoices, B2B transfers
+- Callback verification from a raw pair or a form mapping
+- Calls that move money are never resent after an ambiguous failure; `OutcomeUnknownError` carries the `order_id`
+- Reads retry with backoff, connection failures retry because nothing was sent
+- Strict `Decimal` amounts, constant time signature checks, private key kept as a secret
+- goodconf settings, endpoint paths and messages are configurable

epoint_python_sdk-0.2.0/LICENSE

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

epoint_python_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: epoint-python-sdk
+Version: 0.2.0
+Summary: Typed Python client for the Epoint (epoint.az) payment gateway, sync and async, safe against double charges.
+Project-URL: Homepage, https://theqiyas.cc/projects/epoint-python-sdk/
+Project-URL: Source, https://github.com/qiyascc/epoint-python-sdk
+Project-URL: Author, https://theqiyas.cc
+Project-URL: Issues, https://github.com/qiyascc/epoint-python-sdk/issues
+Project-URL: Changelog, https://github.com/qiyascc/epoint-python-sdk/blob/main/CHANGELOG.md
+Author-email: qiyascc <qiyasturk@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: azerbaijan,azn,checkout,epoint,gateway,payment,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: goodconf>=7.1
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: goodconf[toml]>=7.1; extra == 'dev'
+Requires-Dist: goodconf[yaml]>=7.1; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: toml
+Requires-Dist: goodconf[toml]>=7.1; extra == 'toml'
+Provides-Extra: yaml
+Requires-Dist: goodconf[yaml]>=7.1; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# epoint-python-sdk
+
+[![Python](https://img.shields.io/badge/python-3.10%20to%203.13-3776AB?logo=python&logoColor=white)](https://www.python.org)
+[![Epoint](https://img.shields.io/badge/gateway-epoint.az-0B5FFF)](https://epoint.az)
+[![Typed](https://img.shields.io/badge/typing-mypy-2A6DB2)](https://mypy-lang.org)
+[![Async](https://img.shields.io/badge/sync%20%2B%20async-httpx-5A45FF)](https://www.python-httpx.org)
+[![Ruff](https://img.shields.io/badge/lint-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff)
+[![Apple Pay](https://img.shields.io/badge/Apple%20Pay-supported-000000?logo=applepay&logoColor=white)](#apple-pay-and-google-pay)
+[![Google Pay](https://img.shields.io/badge/Google%20Pay-supported-4285F4?logo=googlepay&logoColor=white)](#apple-pay-and-google-pay)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/qiyascc/epoint-python-sdk/blob/main/LICENSE)
+
+Typed Python client for the [Epoint](https://epoint.az) payment gateway. Sync and async, every endpoint, signed callbacks, and retry rules built so a payment is never sent twice.
+
+```bash
+pip install epoint-python-sdk
+```
+
+## Pay
+
+```python
+from epoint_sdk import Epoint
+
+with Epoint("i000000001", "PRIVATE_KEY", success_url="https://shop.az/ok", error_url="https://shop.az/fail") as ep:
+    checkout = ep.payments.create("19.90", "ORDER-1042", description="Pro plan")
+    redirect(checkout.redirect_url)
+```
+
+## Confirm
+
+```python
+tx = ep.verify_callback(request.POST)
+if tx.paid:
+    fulfil(tx.order_id, tx.amount, tx.transaction)
+```
+
+Never trust the redirect alone. Use the signed callback, or ask the gateway:
+
+```python
+ep.payments.status(checkout.transaction).paid
+```
+
+## Apple Pay and Google Pay
+
+```python
+widget = ep.widgets.create("19.90", "ORDER-1043", "Pro plan")
+```
+
+```html
+<iframe src="{{ widget.widget_url }}" allow="payment" title="Apple Pay / Google Pay"></iframe>
+<script>
+addEventListener("message", (e) => {
+  if (e.origin !== "{{ widget.origin }}") return;
+  fetch("/orders/1043/check/", { method: "POST" });
+});
+</script>
+```
+
+The page needs `Permissions-Policy: payment=(self "https://epoint.az")`. The `postMessage` is a hint only: `WidgetMessage.from_event(data)` reads it, then confirm on the server with `ep.payments.status(widget.transaction)` or the signed callback. Epoint enables token payments per merchant. `ep.widgets.split(...)` is the split variant.
+
+## Safety
+
+| Situation | What the client does |
+| --- | --- |
+| Connection refused, nothing sent | Retries, then `NotSentError` |
+| Timeout, cut connection or 5xx on a call that moves money | No retry, `OutcomeUnknownError` with the `order_id` |
+| Same failure on a read (status, card, lists) | Retries with backoff |
+| 429 | Retries, the gateway did not process it |
+| `status: error` from the gateway | `GatewayError` with `code` and `trace_id` |
+| Declined card on a direct charge | Returns `Transaction` with `failed`, never raises |
+| Amount like `1.005`, `0`, `NaN` or `True` | `InvalidRequestError` before anything is sent |
+| `base_url` over plain http | `ConfigurationError`, except localhost or `allow_insecure_http` |
+| Callback `data` over 64 KB | Rejected before hashing |
+| Callback for another order or amount | `tx.matches(order_id=..., amount=...)` is `False` |
+
+Reuse the same `order_id` when you retry. Epoint refuses a used one, so a double click or a crash can not charge twice. Amounts are `Decimal` end to end, and signatures are compared in constant time.
+
+## Endpoints
+
+| Namespace | Methods |
+| --- | --- |
+| `payments` | `create` `form` `status` `reverse` `hold` `capture` |
+| `cards` | `register` `register_and_pay` `charge` `status` `payout` |
+| `split` | `create` `charge` `register_and_pay` |
+| `installments` | `plans` `create` |
+| `wallets` | `list` `pay` |
+| `widgets` | `create` `split` (Apple Pay, Google Pay) |
+| `invoices` | `create` `update` `get` `list` `send_sms` `send_email` |
+| `transfers` | `create` `status` (B2B) |
+| client | `heartbeat` `verify_callback` `request` |
+
+`AsyncEpoint` has the same methods, awaited.
+
+## Config
+
+Pass values in code, or set `EPOINT_PUBLIC_KEY`, `EPOINT_PRIVATE_KEY`, `EPOINT_SUCCESS_URL`, `EPOINT_ERROR_URL`, `EPOINT_LANGUAGE`, `EPOINT_TIMEOUT`, `EPOINT_MAX_RETRIES`, or put them in `epoint.toml`. Every path is a setting (`EPOINT_ENDPOINTS__PAYMENT=...`) and `base_url` can point at a sandbox such as [epoint-sandbox](https://github.com/martian56/epoint-sandbox). Messages live in `messages.yaml` and can be replaced with `messages.use(...)`.
+
+## Develop
+
+```bash
+pip install -e ".[dev]" && pytest && ruff check . && mypy src
+```
+
+## Links
+
+- Source code: [github.com/qiyascc/epoint-python-sdk](https://github.com/qiyascc/epoint-python-sdk)
+- PyPI: [pypi.org/project/epoint-python-sdk](https://pypi.org/project/epoint-python-sdk/)
+- Project page: [theqiyas.cc/projects/epoint-python-sdk](https://theqiyas.cc/projects/epoint-python-sdk/)
+- Author: [Qiyas Sadıqov](https://theqiyas.cc), more projects at [theqiyas.cc](https://theqiyas.cc)
+
+## License
+
+MIT

epoint_python_sdk-0.2.0/README.md

@@ -0,0 +1,112 @@
+# epoint-python-sdk
+
+[![Python](https://img.shields.io/badge/python-3.10%20to%203.13-3776AB?logo=python&logoColor=white)](https://www.python.org)
+[![Epoint](https://img.shields.io/badge/gateway-epoint.az-0B5FFF)](https://epoint.az)
+[![Typed](https://img.shields.io/badge/typing-mypy-2A6DB2)](https://mypy-lang.org)
+[![Async](https://img.shields.io/badge/sync%20%2B%20async-httpx-5A45FF)](https://www.python-httpx.org)
+[![Ruff](https://img.shields.io/badge/lint-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff)
+[![Apple Pay](https://img.shields.io/badge/Apple%20Pay-supported-000000?logo=applepay&logoColor=white)](#apple-pay-and-google-pay)
+[![Google Pay](https://img.shields.io/badge/Google%20Pay-supported-4285F4?logo=googlepay&logoColor=white)](#apple-pay-and-google-pay)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/qiyascc/epoint-python-sdk/blob/main/LICENSE)
+
+Typed Python client for the [Epoint](https://epoint.az) payment gateway. Sync and async, every endpoint, signed callbacks, and retry rules built so a payment is never sent twice.
+
+```bash
+pip install epoint-python-sdk
+```
+
+## Pay
+
+```python
+from epoint_sdk import Epoint
+
+with Epoint("i000000001", "PRIVATE_KEY", success_url="https://shop.az/ok", error_url="https://shop.az/fail") as ep:
+    checkout = ep.payments.create("19.90", "ORDER-1042", description="Pro plan")
+    redirect(checkout.redirect_url)
+```
+
+## Confirm
+
+```python
+tx = ep.verify_callback(request.POST)
+if tx.paid:
+    fulfil(tx.order_id, tx.amount, tx.transaction)
+```
+
+Never trust the redirect alone. Use the signed callback, or ask the gateway:
+
+```python
+ep.payments.status(checkout.transaction).paid
+```
+
+## Apple Pay and Google Pay
+
+```python
+widget = ep.widgets.create("19.90", "ORDER-1043", "Pro plan")
+```
+
+```html
+<iframe src="{{ widget.widget_url }}" allow="payment" title="Apple Pay / Google Pay"></iframe>
+<script>
+addEventListener("message", (e) => {
+  if (e.origin !== "{{ widget.origin }}") return;
+  fetch("/orders/1043/check/", { method: "POST" });
+});
+</script>
+```
+
+The page needs `Permissions-Policy: payment=(self "https://epoint.az")`. The `postMessage` is a hint only: `WidgetMessage.from_event(data)` reads it, then confirm on the server with `ep.payments.status(widget.transaction)` or the signed callback. Epoint enables token payments per merchant. `ep.widgets.split(...)` is the split variant.
+
+## Safety
+
+| Situation | What the client does |
+| --- | --- |
+| Connection refused, nothing sent | Retries, then `NotSentError` |
+| Timeout, cut connection or 5xx on a call that moves money | No retry, `OutcomeUnknownError` with the `order_id` |
+| Same failure on a read (status, card, lists) | Retries with backoff |
+| 429 | Retries, the gateway did not process it |
+| `status: error` from the gateway | `GatewayError` with `code` and `trace_id` |
+| Declined card on a direct charge | Returns `Transaction` with `failed`, never raises |
+| Amount like `1.005`, `0`, `NaN` or `True` | `InvalidRequestError` before anything is sent |
+| `base_url` over plain http | `ConfigurationError`, except localhost or `allow_insecure_http` |
+| Callback `data` over 64 KB | Rejected before hashing |
+| Callback for another order or amount | `tx.matches(order_id=..., amount=...)` is `False` |
+
+Reuse the same `order_id` when you retry. Epoint refuses a used one, so a double click or a crash can not charge twice. Amounts are `Decimal` end to end, and signatures are compared in constant time.
+
+## Endpoints
+
+| Namespace | Methods |
+| --- | --- |
+| `payments` | `create` `form` `status` `reverse` `hold` `capture` |
+| `cards` | `register` `register_and_pay` `charge` `status` `payout` |
+| `split` | `create` `charge` `register_and_pay` |
+| `installments` | `plans` `create` |
+| `wallets` | `list` `pay` |
+| `widgets` | `create` `split` (Apple Pay, Google Pay) |
+| `invoices` | `create` `update` `get` `list` `send_sms` `send_email` |
+| `transfers` | `create` `status` (B2B) |
+| client | `heartbeat` `verify_callback` `request` |
+
+`AsyncEpoint` has the same methods, awaited.
+
+## Config
+
+Pass values in code, or set `EPOINT_PUBLIC_KEY`, `EPOINT_PRIVATE_KEY`, `EPOINT_SUCCESS_URL`, `EPOINT_ERROR_URL`, `EPOINT_LANGUAGE`, `EPOINT_TIMEOUT`, `EPOINT_MAX_RETRIES`, or put them in `epoint.toml`. Every path is a setting (`EPOINT_ENDPOINTS__PAYMENT=...`) and `base_url` can point at a sandbox such as [epoint-sandbox](https://github.com/martian56/epoint-sandbox). Messages live in `messages.yaml` and can be replaced with `messages.use(...)`.
+
+## Develop
+
+```bash
+pip install -e ".[dev]" && pytest && ruff check . && mypy src
+```
+
+## Links
+
+- Source code: [github.com/qiyascc/epoint-python-sdk](https://github.com/qiyascc/epoint-python-sdk)
+- PyPI: [pypi.org/project/epoint-python-sdk](https://pypi.org/project/epoint-python-sdk/)
+- Project page: [theqiyas.cc/projects/epoint-python-sdk](https://theqiyas.cc/projects/epoint-python-sdk/)
+- Author: [Qiyas Sadıqov](https://theqiyas.cc), more projects at [theqiyas.cc](https://theqiyas.cc)
+
+## License
+
+MIT

epoint_python_sdk-0.2.0/examples/django_view.py

@@ -0,0 +1,23 @@
+from django.http import HttpResponse, HttpResponseBadRequest
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+
+from epoint_sdk import Epoint, SignatureError
+
+epoint = Epoint()
+
+
+@csrf_exempt
+@require_POST
+def epoint_callback(request):
+    try:
+        tx = epoint.verify_callback(request.POST)
+    except SignatureError:
+        return HttpResponseBadRequest()
+    if tx.paid:
+        mark_paid(tx.order_id, tx.amount, tx.transaction)
+    return HttpResponse("OK")
+
+
+def mark_paid(order_id, amount, transaction):
+    raise NotImplementedError

epoint_python_sdk-0.2.0/examples/epoint.toml

@@ -0,0 +1,6 @@
+public_key = "i000000001"
+private_key = "your-private-key"
+success_url = "https://shop.az/payment/ok"
+error_url = "https://shop.az/payment/fail"
+language = "az"
+timeout = 30

epoint_python_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "epoint-python-sdk"
+dynamic = ["version"]
+description = "Typed Python client for the Epoint (epoint.az) payment gateway, sync and async, safe against double charges."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "qiyascc", email = "qiyasturk@gmail.com" }]
+keywords = ["epoint", "payment", "gateway", "azerbaijan", "azn", "sdk", "checkout"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24,<1", "goodconf>=7.1", "pydantic>=2.7", "PyYAML>=6"]
+
+[project.optional-dependencies]
+toml = ["goodconf[toml]>=7.1"]
+yaml = ["goodconf[yaml]>=7.1"]
+dev = ["epoint-python-sdk[toml,yaml]", "pytest>=7", "pytest-asyncio>=0.21", "ruff>=0.4", "mypy>=1.8", "types-PyYAML"]
+
+[project.urls]
+Homepage = "https://theqiyas.cc/projects/epoint-python-sdk/"
+Source = "https://github.com/qiyascc/epoint-python-sdk"
+Author = "https://theqiyas.cc"
+Issues = "https://github.com/qiyascc/epoint-python-sdk/issues"
+Changelog = "https://github.com/qiyascc/epoint-python-sdk/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/epoint_sdk/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/epoint_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/epoint_sdk", "tests", "examples", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E731", "UP006", "UP007", "UP035", "UP045"]
+
+[tool.mypy]
+python_version = "3.10"
+plugins = ["pydantic.mypy"]
+warn_unused_ignores = true

epoint_python_sdk-0.2.0/src/epoint_sdk/__init__.py

@@ -0,0 +1,73 @@
+from . import messages, signing
+from ._version import __version__
+from .callbacks import callback_form, verify_callback
+from .client import AsyncEpoint, Epoint
+from .config import Settings, load_settings
+from .enums import CardStatus, Currency, Language, OperationCode, Status
+from .errors import (
+    ConfigurationError,
+    EpointError,
+    GatewayError,
+    HTTPStatusError,
+    InvalidRequestError,
+    NotSentError,
+    OutcomeUnknownError,
+    SignatureError,
+    TransportError,
+)
+from .models import (
+    Callback,
+    Card,
+    CardRegistration,
+    CheckoutForm,
+    InstallmentPlan,
+    Invoice,
+    Redirect,
+    Result,
+    Transaction,
+    Transfer,
+    Wallet,
+    Widget,
+    WidgetMessage,
+    origin_of,
+)
+
+__all__ = [
+    "__version__",
+    "Epoint",
+    "AsyncEpoint",
+    "Settings",
+    "load_settings",
+    "messages",
+    "signing",
+    "verify_callback",
+    "callback_form",
+    "Status",
+    "CardStatus",
+    "Currency",
+    "Language",
+    "OperationCode",
+    "Callback",
+    "Card",
+    "CardRegistration",
+    "CheckoutForm",
+    "InstallmentPlan",
+    "Invoice",
+    "Redirect",
+    "Result",
+    "Transaction",
+    "Transfer",
+    "Wallet",
+    "Widget",
+    "WidgetMessage",
+    "origin_of",
+    "EpointError",
+    "ConfigurationError",
+    "InvalidRequestError",
+    "SignatureError",
+    "TransportError",
+    "NotSentError",
+    "OutcomeUnknownError",
+    "HTTPStatusError",
+    "GatewayError",
+]