bepaid 0.1.0__tar.gz

bepaid-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: bepaid
+Version: 0.1.0
+Summary: Client for the bePaid payment API (bepaid.by)
+Author: amnesiaof
+Author-email: amnesiaof <dolombovskyyalexs@gmail.com>
+License-Expression: MIT
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Python: >=3.10
+Project-URL: repository, https://github.com/amnesiaof/bepaid-py
+Project-URL: homepage, https://github.com/amnesiaof/bepaid-py
+Description-Content-Type: text/markdown
+
+# bepaid
+
+Python client for the [bePaid payment API](https://docs.bepaid.by) (bepaid.by).
+
+Covers the Gateway API (card payments, tokenization, capture, void, refunds),
+the hosted Checkout API, and the Direct/APM API (alternative payment methods).
+Built on `httpx` and `pydantic`.
+
+## Install
+
+```bash
+uv add bepaid
+# or
+pip install bepaid
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+```python
+from bepaid import BepaidClient
+from bepaid.models import PaymentRequest, CreditCardRaw
+
+client = BepaidClient("shop_id", "secret_key")
+
+# amounts are strings in minor units, e.g. "700" = 7.00 BYN
+payment = client.create_payment(
+    PaymentRequest(
+        amount="700",
+        currency="BYN",
+        test=True,
+        description="Order #123",
+        tracking_id="order-123",
+        credit_card=CreditCardRaw(
+            number="4242424242424242",
+            verification_value="123",
+            holder="John Smith",
+            exp_month=10,
+            exp_year=2030,
+            save_card=True,
+        ),
+    )
+)
+```
+
+Use the client as a context manager to close the underlying HTTP connection:
+
+```python
+with BepaidClient("shop_id", "secret_key") as client:
+    payment = client.create_payment(...)
+```
+
+### Authorization with 3-D Secure
+
+```python
+auth = client.create_authorization(AuthorizationRequest(amount=700, currency="BYN", ...))
+# redirect the customer to auth.redirect_url, then poll for the result:
+tx = client.get_transaction(auth.uid)
+```
+
+### Hosted checkout
+
+```python
+checkout = client.create_checkout(
+    CheckoutRequest(
+        transaction_type="payment",
+        order=CheckoutOrder(currency="BYN", amount=700, description="Order #123"),
+        settings=CheckoutSettings(
+            return_url="https://example.com/return",
+            notification_url="https://example.com/webhook",
+        ),
+    )
+)
+# redirect the customer to checkout.redirect_url
+```
+
+### Tokenization
+
+```python
+token = client.create_token(
+    CreateTokenRequest(
+        number="4200000000000000",
+        holder="John Smith",
+        exp_month="05",
+        exp_year="2028",
+        contract=["recurring"],
+    )
+)
+# store token.token, use it later without re-entering card details
+```
+
+### APM payments (Direct API)
+
+```python
+apm = client.create_apm_payment(
+    ApmPaymentRequest(
+        amount=700,
+        currency="BYN",
+        payment_method={"type": "erip", "service_no": "0000000001"},
+    )
+)
+```
+
+### Webhooks
+
+```python
+from bepaid.client import verify_webhook_auth
+from bepaid.models import WebhookNotification
+
+assert verify_webhook_auth(authorization_header, shop_id, secret_key)
+notification = WebhookNotification.model_validate_json(raw_body)
+```
+
+## API coverage
+
+| Group     | Operations |
+|-----------|------------|
+| Gateway   | `create_payment`, `create_authorization`, `capture`, `void`, `refund`, `get_transaction` |
+| Tokens    | `create_token` |
+| Checkout  | `create_checkout`, `get_checkout_status`, `validate_apple_pay` |
+| Direct    | `create_apm_payment`, `apm_refund`, `apm_full_refund` |
+| Webhooks  | verification + payload parsing |
+
+## License
+
+MIT

bepaid-0.1.0/README.md

@@ -0,0 +1,127 @@
+# bepaid
+
+Python client for the [bePaid payment API](https://docs.bepaid.by) (bepaid.by).
+
+Covers the Gateway API (card payments, tokenization, capture, void, refunds),
+the hosted Checkout API, and the Direct/APM API (alternative payment methods).
+Built on `httpx` and `pydantic`.
+
+## Install
+
+```bash
+uv add bepaid
+# or
+pip install bepaid
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+```python
+from bepaid import BepaidClient
+from bepaid.models import PaymentRequest, CreditCardRaw
+
+client = BepaidClient("shop_id", "secret_key")
+
+# amounts are strings in minor units, e.g. "700" = 7.00 BYN
+payment = client.create_payment(
+    PaymentRequest(
+        amount="700",
+        currency="BYN",
+        test=True,
+        description="Order #123",
+        tracking_id="order-123",
+        credit_card=CreditCardRaw(
+            number="4242424242424242",
+            verification_value="123",
+            holder="John Smith",
+            exp_month=10,
+            exp_year=2030,
+            save_card=True,
+        ),
+    )
+)
+```
+
+Use the client as a context manager to close the underlying HTTP connection:
+
+```python
+with BepaidClient("shop_id", "secret_key") as client:
+    payment = client.create_payment(...)
+```
+
+### Authorization with 3-D Secure
+
+```python
+auth = client.create_authorization(AuthorizationRequest(amount=700, currency="BYN", ...))
+# redirect the customer to auth.redirect_url, then poll for the result:
+tx = client.get_transaction(auth.uid)
+```
+
+### Hosted checkout
+
+```python
+checkout = client.create_checkout(
+    CheckoutRequest(
+        transaction_type="payment",
+        order=CheckoutOrder(currency="BYN", amount=700, description="Order #123"),
+        settings=CheckoutSettings(
+            return_url="https://example.com/return",
+            notification_url="https://example.com/webhook",
+        ),
+    )
+)
+# redirect the customer to checkout.redirect_url
+```
+
+### Tokenization
+
+```python
+token = client.create_token(
+    CreateTokenRequest(
+        number="4200000000000000",
+        holder="John Smith",
+        exp_month="05",
+        exp_year="2028",
+        contract=["recurring"],
+    )
+)
+# store token.token, use it later without re-entering card details
+```
+
+### APM payments (Direct API)
+
+```python
+apm = client.create_apm_payment(
+    ApmPaymentRequest(
+        amount=700,
+        currency="BYN",
+        payment_method={"type": "erip", "service_no": "0000000001"},
+    )
+)
+```
+
+### Webhooks
+
+```python
+from bepaid.client import verify_webhook_auth
+from bepaid.models import WebhookNotification
+
+assert verify_webhook_auth(authorization_header, shop_id, secret_key)
+notification = WebhookNotification.model_validate_json(raw_body)
+```
+
+## API coverage
+
+| Group     | Operations |
+|-----------|------------|
+| Gateway   | `create_payment`, `create_authorization`, `capture`, `void`, `refund`, `get_transaction` |
+| Tokens    | `create_token` |
+| Checkout  | `create_checkout`, `get_checkout_status`, `validate_apple_pay` |
+| Direct    | `create_apm_payment`, `apm_refund`, `apm_full_refund` |
+| Webhooks  | verification + payload parsing |
+
+## License
+
+MIT

bepaid-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "bepaid"
+version = "0.1.0"
+description = "Client for the bePaid payment API (bepaid.by)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[[project.authors]]
+name = "amnesiaof"
+email = "dolombovskyyalexs@gmail.com"
+
+[project.urls]
+repository = "https://github.com/amnesiaof/bepaid-py"
+homepage = "https://github.com/amnesiaof/bepaid-py"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]

bepaid-0.1.0/pyproject.toml.orig

@@ -0,0 +1,27 @@
+[project]
+name = "bepaid"
+version = "0.1.0"
+description = "Client for the bePaid payment API (bepaid.by)"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "amnesiaof", email = "dolombovskyyalexs@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+repository = "https://github.com/amnesiaof/bepaid-py"
+homepage = "https://github.com/amnesiaof/bepaid-py"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

bepaid-0.1.0/src/bepaid/__init__.py

@@ -0,0 +1,7 @@
+"""bePaid payment API client (bepaid.by)."""
+
+from .client import BepaidClient
+from .errors import ApiError, BepaidError
+
+__all__ = ["ApiError", "BepaidClient", "BepaidError"]
+__version__ = "0.1.0"

bepaid-0.1.0/src/bepaid/client.py

@@ -0,0 +1,210 @@
+"""httpx-based client for the bePaid API (bepaid.by)."""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, Self
+
+import httpx
+from pydantic import BaseModel
+
+from .errors import ApiError
+from .models import (
+    ApmPaymentRequest,
+    ApmPaymentResponse,
+    ApmRefundRequest,
+    ApmRefundResponse,
+    AuthorizationRequest,
+    AuthorizationResponse,
+    CaptureRequest,
+    CaptureResponse,
+    CheckoutRequest,
+    CheckoutResponse,
+    CheckoutStatus,
+    CreateTokenRequest,
+    PaymentRequest,
+    PaymentResponse,
+    RefundRequest,
+    RefundResponse,
+    TokenResponse,
+    Transaction,
+    VoidRequest,
+    VoidResponse,
+)
+
+DEFAULT_GATEWAY_URL = "https://gateway.bepaid.by"
+DEFAULT_CHECKOUT_URL = "https://checkout.bepaid.by"
+DEFAULT_API_URL = "https://api.bepaid.by"
+
+_HEADERS = {"Content-Type": "application/json", "Accept": "application/json"}
+
+
+class BepaidClient:
+    def __init__(
+        self,
+        shop_id: str | int,
+        secret_key: str,
+        *,
+        timeout: float = 30.0,
+        base_gateway_url: str = DEFAULT_GATEWAY_URL,
+        base_checkout_url: str = DEFAULT_CHECKOUT_URL,
+        base_api_url: str = DEFAULT_API_URL,
+    ) -> None:
+        credentials = f"{shop_id}:{secret_key}"
+        self._auth = "Basic " + base64.b64encode(credentials.encode()).decode()
+        self._base_gateway = base_gateway_url
+        self._base_checkout = base_checkout_url
+        self._base_api = base_api_url
+        self._http = httpx.Client(timeout=timeout, headers=_HEADERS)
+
+    @property
+    def http(self) -> httpx.Client:
+        """The underlying synchronous httpx client (for advanced use)."""
+        return self._http
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ── transport ──────────────────────────────────────────────────────────
+
+    def _request(
+        self, method: str, url: str, body: BaseModel | dict | None = None
+    ) -> dict[str, Any]:
+        resp = self._http.request(
+            method,
+            url,
+            headers={"Authorization": self._auth},
+            json=body.model_dump(by_alias=True, exclude_none=True)
+            if isinstance(body, BaseModel)
+            else body,
+        )
+        if resp.status_code >= 400:
+            data = resp.json()
+            raise ApiError(
+                status=resp.status_code,
+                message=data.get("message", resp.text),
+                errors=data.get("errors"),
+            )
+        return resp.json()
+
+    # ── gateway API ────────────────────────────────────────────────────────
+
+    def create_payment(self, req: PaymentRequest) -> PaymentResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_gateway}/transactions/payments",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return PaymentResponse.model_validate(data["transaction"])
+
+    def create_authorization(self, req: AuthorizationRequest) -> AuthorizationResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_gateway}/transactions/authorizations",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return AuthorizationResponse.model_validate(data["transaction"])
+
+    def capture(self, req: CaptureRequest) -> CaptureResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_gateway}/transactions/captures",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return CaptureResponse.model_validate(data["transaction"])
+
+    def void(self, req: VoidRequest) -> VoidResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_gateway}/transactions/voids",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return VoidResponse.model_validate(data["transaction"])
+
+    def refund(self, req: RefundRequest) -> RefundResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_gateway}/transactions/refunds",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return RefundResponse.model_validate(data["transaction"])
+
+    def get_transaction(self, uid: str) -> Transaction:
+        data = self._request("GET", f"{self._base_gateway}/transactions/{uid}")
+        return Transaction.model_validate(data["transaction"])
+
+    # ── token API ──────────────────────────────────────────────────────────
+
+    def create_token(self, req: CreateTokenRequest) -> TokenResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_gateway}/credit_cards",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return TokenResponse.model_validate(data)
+
+    # ── checkout API ───────────────────────────────────────────────────────
+
+    def create_checkout(self, req: CheckoutRequest) -> CheckoutResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_checkout}/ctp/api/checkouts",
+            {"checkout": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return CheckoutResponse.model_validate(data["checkout"])
+
+    def get_checkout_status(self, token: str) -> CheckoutStatus:
+        data = self._request("GET", f"{self._base_checkout}/ctp/api/checkouts/{token}")
+        return CheckoutStatus.model_validate(data["checkout"])
+
+    def validate_apple_pay(self, url: str, token: str | None = None) -> dict[str, Any]:
+        return self._request(
+            "POST",
+            f"{self._base_checkout}/ctp/api/apple_pay/validate",
+            {"url": url, "token": token, "context": "merchant"},
+        )
+
+    # ── direct / APM API ───────────────────────────────────────────────────
+
+    def create_apm_payment(self, req: ApmPaymentRequest) -> ApmPaymentResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_api}/beyag/transactions/payments",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return ApmPaymentResponse.model_validate(data["transaction"])
+
+    def apm_refund(self, req: ApmRefundRequest) -> ApmRefundResponse:
+        data = self._request(
+            "POST",
+            f"{self._base_api}/beyag/transactions/refunds",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return ApmRefundResponse.model_validate(data["transaction"])
+
+    def apm_full_refund(
+        self, parent_uid: str, reason: str, amount: int | None = None
+    ) -> ApmRefundResponse:
+        req = ApmRefundRequest(parent_uid=parent_uid, reason=reason, amount=amount)
+        data = self._request(
+            "POST",
+            f"{self._base_api}/beyag/refunds",
+            {"request": req.model_dump(by_alias=True, exclude_none=True)},
+        )
+        return ApmRefundResponse.model_validate(data["transaction"])
+
+
+# ── webhook helpers ──────────────────────────────────────────────────────────
+
+
+def verify_webhook_auth(
+    authorization_header: str, shop_id: str, secret_key: str
+) -> bool:
+    expected = "Basic " + base64.b64encode(f"{shop_id}:{secret_key}".encode()).decode()
+    return authorization_header == expected

bepaid-0.1.0/src/bepaid/errors.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class BepaidError(Exception):
+    """Base exception for bepaid errors."""
+
+
+@dataclass
+class ApiError(BepaidError):
+    """An error response returned by the bePaid API."""
+
+    status: int
+    message: str
+    errors: dict | None = None
+
+    def __str__(self) -> str:
+        return f"API error {self.status}: {self.message}"

bepaid-0.1.0/src/bepaid/models.py

@@ -0,0 +1,371 @@
+"""Pydantic models for the bePaid API (aliases use camelCase as the API expects)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class CamelModel(BaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+
+class BillingAddress(CamelModel):
+    first_name: str | None = None
+    last_name: str | None = None
+    country: str | None = None
+    city: str | None = None
+    state: str | None = None
+    zip: str | None = None
+    address: str | None = None
+    phone: str | None = None
+
+
+class Customer(CamelModel):
+    first_name: str | None = None
+    last_name: str | None = None
+    middle_name: str | None = None
+    ip: str | None = None
+    email: str | None = None
+    device_id: str | None = None
+    birth_date: str | None = None
+
+
+class BrowserInfo(CamelModel):
+    screen_width: int | None = None
+    screen_height: int | None = None
+    screen_color_depth: int | None = None
+    language: str | None = None
+    java_enabled: bool | None = None
+    user_agent: str | None = None
+    time_zone: int | None = None
+    time_zone_name: str | None = None
+    accept_header: str | None = None
+    window_height: int | None = None
+    window_width: int | None = None
+
+
+class AdditionalData(CamelModel):
+    browser: BrowserInfo | None = None
+    contract: list[str] | None = None
+    referer: str | None = None
+
+
+class CreditCardRaw(CamelModel):
+    number: str
+    verification_value: str | None = None
+    holder: str | None = None
+    exp_month: int | None = None
+    exp_year: int | None = None
+    save_card: bool | None = None
+    token: str | None = None
+
+
+class CreditCardInfo(CamelModel):
+    holder: str | None = None
+    stamp: str | None = None
+    brand: str | None = None
+    last_4: str | None = None
+    first_1: str | None = None
+    bin: str | None = None
+    exp_month: int | None = None
+    exp_year: int | None = None
+    token: str | None = None
+
+
+class PaymentInfo(CamelModel):
+    auth_code: str | None = None
+    bank_code: str | None = None
+    rrn: str | None = None
+    ref_id: str | None = None
+    message: str | None = None
+    amount: int | None = None
+    currency: str | None = None
+    billing_descriptor: str | None = None
+    gateway_id: int | None = None
+    status: str | None = None
+
+
+class ThreeDSecureVerification(CamelModel):
+    status: str | None = None
+    message: str | None = None
+    pa_res_url: str | None = None
+    eci: str | None = None
+
+
+# ── gateway ───────────────────────────────────────────────────────────────────
+
+
+class PaymentRequest(CamelModel):
+    amount: str
+    currency: str
+    test: bool
+    description: str
+    tracking_id: str
+    language: str | None = None
+    notification_url: str | None = None
+    billing_address: BillingAddress | None = None
+    credit_card: CreditCardRaw | None = None
+    customer: Customer | None = None
+    additional_data: AdditionalData | None = None
+
+
+class PaymentResponse(CamelModel):
+    tracking_id: str | None = None
+    uid: str
+
+
+class AuthorizationRequest(CamelModel):
+    amount: int
+    currency: str
+    description: str
+    tracking_id: str
+    payment_method_type: str | None = None
+    test: bool | None = None
+    credit_card: CreditCardRaw | None = None
+    customer: Customer | None = None
+    billing_address: BillingAddress | None = None
+
+
+class AuthorizationResponse(CamelModel):
+    uid: str
+    status: str | None = None
+    redirect_url: str | None = None
+    three_d_secure_verification: ThreeDSecureVerification | None = None
+
+
+class Transaction(CamelModel):
+    uid: str
+    status: str | None = None
+    amount: int | None = None
+    currency: str | None = None
+    description: str | None = None
+    tracking_id: str | None = None
+    message: str | None = None
+    type: str | None = None
+    test: bool | None = None
+    payment: PaymentInfo | None = None
+    credit_card: CreditCardInfo | None = None
+    code: str | None = None
+    friendly_message: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+    paid_at: str | None = None
+    receipt_url: str | None = None
+    redirect_url: str | None = None
+
+
+class CaptureRequest(CamelModel):
+    parent_uid: str
+    amount: int
+    tracking_id: str | None = None
+    additional_data: AdditionalData | None = None
+
+
+class CaptureResponse(CamelModel):
+    uid: str
+    status: str | None = None
+    type: str | None = None
+    parent_uid: str | None = None
+    amount: int | None = None
+    currency: str | None = None
+    code: str | None = None
+
+
+class VoidRequest(CamelModel):
+    parent_uid: str
+    amount: int
+    tracking_id: str | None = None
+    additional_data: AdditionalData | None = None
+
+
+class VoidResponse(CamelModel):
+    uid: str
+    status: str | None = None
+    type: str | None = None
+    message: str | None = None
+    code: str | None = None
+    tracking_id: str | None = None
+    receipt_url: str | None = None
+
+
+class RefundRequest(CamelModel):
+    parent_uid: str
+    amount: int
+    reason: str
+    tracking_id: str | None = None
+    additional_data: AdditionalData | None = None
+
+
+class RefundResponse(CamelModel):
+    uid: str | None = None
+    parent_uid: str | None = None
+    type: str | None = None
+    status: str | None = None
+    message: str | None = None
+    amount: int | None = None
+    currency: str | None = None
+    created_at: str | None = None
+    reason: str | None = None
+    refund: dict[str, Any] | None = None
+
+
+# ── token API ─────────────────────────────────────────────────────────────────
+
+
+class CreateTokenRequest(CamelModel):
+    number: str
+    holder: str
+    exp_month: str
+    exp_year: str
+    contract: list[str] | None = None
+
+
+class TokenResponse(CamelModel):
+    holder: str | None = None
+    stamp: str | None = None
+    brand: str | None = None
+    last_4: str | None = None
+    first_1: str | None = None
+    token: str | None = None
+    exp_month: int | None = None
+    exp_year: int | None = None
+
+
+# ── checkout API ──────────────────────────────────────────────────────────────
+
+
+class CheckoutSettings(CamelModel):
+    return_url: str | None = None
+    success_url: str | None = None
+    decline_url: str | None = None
+    fail_url: str | None = None
+    cancel_url: str | None = None
+    notification_url: str | None = None
+    button_next_text: str | None = None
+    auto_pay: bool | None = None
+    language: str | None = None
+
+
+class PaymentMethod(CamelModel):
+    types: list[str] | None = None
+
+
+class CheckoutCreditCard(CamelModel):
+    token: str | None = None
+
+
+class CheckoutOrder(CamelModel):
+    currency: str
+    amount: int
+    description: str | None = None
+    tracking_id: str | None = None
+
+
+class CheckoutRequest(CamelModel):
+    test: bool | None = None
+    transaction_type: str = "payment"
+    attempts: int | None = None
+    iframe: bool | None = None
+    settings: CheckoutSettings | None = None
+    payment_method: PaymentMethod | None = None
+    credit_card: CheckoutCreditCard | None = None
+    order: CheckoutOrder
+    customer: Customer | None = None
+
+
+class CheckoutResponse(CamelModel):
+    token: str
+    redirect_url: str | None = None
+
+
+class CheckoutStatus(CamelModel):
+    token: str | None = None
+    shop_id: int | None = None
+    transaction_type: str | None = None
+    gateway_response: dict[str, Any] | None = None
+    order: dict[str, Any] | None = None
+    settings: CheckoutSettings | None = None
+
+
+# ── direct / APM API ──────────────────────────────────────────────────────────
+
+
+class ApmPaymentRequest(CamelModel):
+    amount: int
+    currency: str
+    description: str | None = None
+    email: str | None = None
+    ip: str | None = None
+    success_url: str | None = None
+    order_id: str | int | None = None
+    tracking_id: str | None = None
+    notification_url: str | None = None
+    expired_at: str | None = None
+    test: bool | None = None
+    language: str | None = None
+    return_url: str | None = None
+    customer: Customer | None = None
+    payment_method: dict[str, Any] = Field(alias="paymentMethod")
+    additional_data: dict[str, Any] | None = None
+
+
+class ApmPaymentResponse(CamelModel):
+    uid: str | None = None
+    status: str | None = None
+    type: str | None = None
+    amount: int | None = None
+    currency: str | None = None
+    message: str | None = None
+    tracking_id: str | None = None
+    test: bool | None = None
+    method_type: str | None = None
+    receipt_url: str | None = None
+    payment: PaymentInfo | None = None
+    created_at: str | None = None
+
+
+class ApmRefundRequest(CamelModel):
+    parent_uid: str
+    reason: str
+    amount: int | None = None
+    tracking_id: str | None = None
+    additional_data: dict[str, Any] | None = None
+
+
+class ApmRefundResponse(CamelModel):
+    uid: str | None = None
+    parent_uid: str | None = None
+    type: str | None = None
+    status: str | None = None
+    message: str | None = None
+    amount: int | None = None
+    currency: str | None = None
+    refund: dict[str, Any] | None = None
+
+
+# ── webhook ───────────────────────────────────────────────────────────────────
+
+
+class WebhookNotification(CamelModel):
+    transaction: WebhookTransaction
+
+
+class WebhookTransaction(CamelModel):
+    uid: str
+    status: str
+    type: str | None = None
+    amount: int | None = None
+    currency: str | None = None
+    description: str | None = None
+    created_at: str | None = None
+    method_type: str | None = None
+    payment: PaymentInfo | None = None
+    message: str | None = None
+    tracking_id: str | None = None
+    test: bool | None = None
+
+
+WebhookNotification.model_rebuild()