wishop 1.2.0__py3-none-any.whl

wishop/__init__.py

@@ -0,0 +1,123 @@
+from .client import VERSION, Wishop
+from .errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ChargeExpiredError,
+    ConflictError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionError,
+    RateLimitError,
+    SignatureVerificationError,
+    UnprocessableError,
+    ValidationError,
+    WishopError,
+)
+from .types import (
+    CHARGE_STATUS_EXPIRED,
+    CHARGE_STATUS_FAILED,
+    CHARGE_STATUS_INITIATED,
+    CHARGE_STATUS_OTP_SENT,
+    CHARGE_STATUS_PAID,
+    CHARGE_STATUS_REFUNDED,
+    EVENT_CHARGE_EXPIRED,
+    EVENT_CHARGE_FAILED,
+    EVENT_CHARGE_PAID,
+    EVENT_CHARGE_REFUNDED,
+    EVENT_PAYOUT_CREATED,
+    EVENT_PAYOUT_FAILED,
+    EVENT_PAYOUT_SUCCEEDED,
+    FAIL_REASON_DECLINED,
+    FAIL_REASON_INSUFFICIENT_FUNDS,
+    FAIL_REASON_INSUFFICIENT_MERCHANT_BALANCE,
+    FAIL_REASON_INTERNAL_ERROR,
+    FAIL_REASON_OTP_ATTEMPTS_EXCEEDED,
+    FAIL_REASON_OTP_EXPIRED,
+    FAIL_REASON_PIN_LOCKED,
+    FAIL_REASON_RECIPIENT_INELIGIBLE,
+    FAIL_REASON_TIMEOUT,
+    FAIL_REASON_WALLET_NOT_FOUND,
+    FEE_BEARER_CUSTOMER,
+    FEE_BEARER_MERCHANT,
+    PAYOUT_STATUS_FAILED,
+    PAYOUT_STATUS_PENDING,
+    PAYOUT_STATUS_SUCCEEDED,
+    REFUND_REASON_DUPLICATE,
+    REFUND_REASON_FRAUDULENT,
+    REFUND_REASON_OTHER,
+    REFUND_REASON_REQUESTED_BY_CUSTOMER,
+    REFUND_STATUS_FAILED,
+    REFUND_STATUS_PENDING,
+    REFUND_STATUS_SUCCEEDED,
+    Charge,
+    ChargeList,
+    Event,
+    EventData,
+    Payout,
+    PayoutList,
+    Refund,
+)
+from .webhooks import DEFAULT_TOLERANCE, construct_event
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "CHARGE_STATUS_EXPIRED",
+    "CHARGE_STATUS_FAILED",
+    "CHARGE_STATUS_INITIATED",
+    "CHARGE_STATUS_OTP_SENT",
+    "CHARGE_STATUS_PAID",
+    "CHARGE_STATUS_REFUNDED",
+    "Charge",
+    "ChargeExpiredError",
+    "ChargeList",
+    "ConflictError",
+    "DEFAULT_TOLERANCE",
+    "EVENT_CHARGE_EXPIRED",
+    "EVENT_CHARGE_FAILED",
+    "EVENT_CHARGE_PAID",
+    "EVENT_CHARGE_REFUNDED",
+    "EVENT_PAYOUT_CREATED",
+    "EVENT_PAYOUT_FAILED",
+    "EVENT_PAYOUT_SUCCEEDED",
+    "Event",
+    "EventData",
+    "FAIL_REASON_DECLINED",
+    "FAIL_REASON_INSUFFICIENT_FUNDS",
+    "FAIL_REASON_INSUFFICIENT_MERCHANT_BALANCE",
+    "FAIL_REASON_INTERNAL_ERROR",
+    "FAIL_REASON_OTP_ATTEMPTS_EXCEEDED",
+    "FAIL_REASON_OTP_EXPIRED",
+    "FAIL_REASON_PIN_LOCKED",
+    "FAIL_REASON_RECIPIENT_INELIGIBLE",
+    "FAIL_REASON_TIMEOUT",
+    "FAIL_REASON_WALLET_NOT_FOUND",
+    "FEE_BEARER_CUSTOMER",
+    "FEE_BEARER_MERCHANT",
+    "NotFoundError",
+    "PAYOUT_STATUS_FAILED",
+    "PAYOUT_STATUS_PENDING",
+    "PAYOUT_STATUS_SUCCEEDED",
+    "PayloadTooLargeError",
+    "Payout",
+    "PayoutList",
+    "PermissionError",
+    "REFUND_REASON_DUPLICATE",
+    "REFUND_REASON_FRAUDULENT",
+    "REFUND_REASON_OTHER",
+    "REFUND_REASON_REQUESTED_BY_CUSTOMER",
+    "REFUND_STATUS_FAILED",
+    "REFUND_STATUS_PENDING",
+    "REFUND_STATUS_SUCCEEDED",
+    "RateLimitError",
+    "Refund",
+    "SignatureVerificationError",
+    "UnprocessableError",
+    "VERSION",
+    "ValidationError",
+    "Wishop",
+    "WishopError",
+    "construct_event",
+]

wishop/_parsing.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from .types import Charge, ChargeList, Event, EventData, Payout, PayoutList, Refund
+
+
+def parse_datetime(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+
+    return datetime.fromisoformat(value)
+
+
+def parse_required_datetime(value: str) -> datetime:
+    parsed = parse_datetime(value)
+
+    if parsed is None:
+        raise ValueError("expected a timestamp")
+
+    return parsed
+
+
+def parse_charge(payload: Dict[str, Any]) -> Charge:
+    return Charge(
+        id=payload["id"],
+        status=payload["status"],
+        currency=payload["currency"],
+        amount=payload["amount"],
+        livemode=payload["livemode"],
+        created_at=parse_required_datetime(payload["created_at"]),
+        order_id=payload.get("order_id"),
+        description=payload.get("description"),
+        fee_bearer=payload.get("fee_bearer"),
+        fee=payload.get("fee"),
+        net=payload.get("net"),
+        customer_debit_amount=payload.get("customer_debit_amount"),
+        amount_refunded=payload.get("amount_refunded"),
+        customer_phone_masked=payload.get("customer_phone_masked"),
+        channel=payload.get("channel"),
+        fail_reason=payload.get("fail_reason"),
+        return_url=payload.get("return_url"),
+        metadata=payload.get("metadata") or {},
+        expires_at=parse_datetime(payload.get("expires_at")),
+        confirmed_at=parse_datetime(payload.get("confirmed_at")),
+        pay_url=payload.get("pay_url"),
+    )
+
+
+def parse_refund(payload: Dict[str, Any]) -> Refund:
+    return Refund(
+        id=payload["id"],
+        charge=payload["charge"],
+        amount=payload["amount"],
+        currency=payload["currency"],
+        status=payload["status"],
+        livemode=payload["livemode"],
+        created_at=parse_required_datetime(payload["created_at"]),
+        reason=payload.get("reason"),
+        description=payload.get("description"),
+    )
+
+
+def parse_charge_list(payload: Dict[str, Any]) -> ChargeList:
+    return ChargeList(
+        charges=[parse_charge(item) for item in payload.get("charges", [])],
+        has_more=bool(payload.get("has_more")),
+    )
+
+
+def parse_payout(payload: Dict[str, Any]) -> Payout:
+    return Payout(
+        id=payload["id"],
+        recipient_phone=payload["recipient_phone"],
+        currency=payload["currency"],
+        amount=payload["amount"],
+        fee=payload["fee"],
+        status=payload["status"],
+        livemode=payload["livemode"],
+        created_at=parse_required_datetime(payload["created_at"]),
+        recipient_name=payload.get("recipient_name"),
+        fail_reason=payload.get("fail_reason"),
+        reference=payload.get("reference"),
+        metadata=payload.get("metadata") or {},
+        completed_at=parse_datetime(payload.get("completed_at")),
+    )
+
+
+def parse_payout_list(payload: Dict[str, Any]) -> PayoutList:
+    return PayoutList(
+        payouts=[parse_payout(item) for item in payload.get("payouts", [])],
+        has_more=payload.get("has_more", False),
+    )
+
+
+def parse_event(payload: Dict[str, Any]) -> Event:
+    data = payload.get("data") or {}
+    charge = data.get("charge")
+    refund = data.get("refund")
+    payout = data.get("payout")
+
+    # Parse only the object the event actually carries. Reading data["charge"]
+    # unconditionally raised KeyError on every payout.* event.
+    return Event(
+        id=payload["id"],
+        type=payload["type"],
+        api_version=payload["api_version"],
+        created_at=parse_required_datetime(payload["created_at"]),
+        livemode=payload["livemode"],
+        data=EventData(
+            object=data.get("object", "charge"),
+            charge=parse_charge(charge) if charge else None,
+            refund=parse_refund(refund) if refund else None,
+            payout=parse_payout(payout) if payout else None,
+        ),
+    )

wishop/_transport.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .errors import APIConnectionError, error_for
+
+DEFAULT_BASE_URL = "https://gatewayapi.wishopht.com"
+DEFAULT_TIMEOUT = 30.0
+
+
+class Transport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        user_agent: str,
+        session: Optional[requests.Session],
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._user_agent = user_agent
+        self._session = session or requests.Session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        headers = {
+            "Authorization": "Bearer " + self._api_key,
+            "Accept": "application/json",
+            "User-Agent": self._user_agent,
+        }
+
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        try:
+            response = self._session.request(
+                method,
+                self._base_url + path,
+                params=params or None,
+                json=body,
+                headers=headers,
+                timeout=self._timeout,
+            )
+        except requests.RequestException as exc:
+            raise APIConnectionError(str(exc)) from exc
+
+        try:
+            envelope = response.json()
+        except ValueError:
+            envelope = {}
+
+        if not response.ok:
+            message = envelope.get("message") or response.reason or "request failed"
+            raise error_for(response.status_code, message, _retry_after(response))
+
+        return envelope.get("data")
+
+
+def _retry_after(response: requests.Response) -> Optional[int]:
+    try:
+        return int(response.headers["Retry-After"])
+    except (KeyError, TypeError, ValueError):
+        return None

wishop/client.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import requests
+
+from ._transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, Transport
+from .resources.charges import Charges
+from .resources.payouts import Payouts
+from .resources.refunds import Refunds
+
+VERSION = "1.2.0"
+
+
+class Wishop:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        transport = Transport(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            user_agent="wishop-python/" + VERSION,
+            session=session,
+        )
+
+        self.charges = Charges(transport)
+        self.refunds = Refunds(transport)
+        self.payouts = Payouts(transport)

wishop/errors.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class WishopError(Exception):
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+class ValidationError(WishopError):
+    pass
+
+
+class AuthenticationError(WishopError):
+    pass
+
+
+class PermissionError(WishopError):
+    pass
+
+
+class NotFoundError(WishopError):
+    pass
+
+
+class ConflictError(WishopError):
+    pass
+
+
+class ChargeExpiredError(WishopError):
+    pass
+
+
+class PayloadTooLargeError(WishopError):
+    pass
+
+
+class UnprocessableError(WishopError):
+    pass
+
+
+class RateLimitError(WishopError):
+    def __init__(self, message: str, status_code: int, retry_after: Optional[int] = None) -> None:
+        super().__init__(message, status_code)
+        self.retry_after = retry_after
+
+
+class APIError(WishopError):
+    pass
+
+
+class APIConnectionError(WishopError):
+    pass
+
+
+class SignatureVerificationError(WishopError):
+    pass
+
+
+_BY_STATUS = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionError,
+    404: NotFoundError,
+    409: ConflictError,
+    410: ChargeExpiredError,
+    413: PayloadTooLargeError,
+    422: UnprocessableError,
+}
+
+
+def error_for(status_code: int, message: str, retry_after: Optional[int] = None) -> WishopError:
+    if status_code == 429:
+        return RateLimitError(message, status_code, retry_after)
+
+    return _BY_STATUS.get(status_code, APIError)(message, status_code)

wishop/resources/charges.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .._parsing import parse_charge, parse_charge_list
+from .._transport import Transport
+from ..types import Charge, ChargeList
+
+
+class Charges:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def create(
+        self,
+        *,
+        amount: str,
+        currency: str,
+        order_id: Optional[str] = None,
+        description: Optional[str] = None,
+        fee_bearer: Optional[str] = None,
+        return_url: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Charge:
+        body: Dict[str, Any] = {"amount": amount, "currency": currency}
+
+        if order_id is not None:
+            body["order_id"] = order_id
+
+        if description is not None:
+            body["description"] = description
+
+        if fee_bearer is not None:
+            body["fee_bearer"] = fee_bearer
+
+        if return_url is not None:
+            body["return_url"] = return_url
+
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        payload = self._transport.request(
+            "POST",
+            "/v1/charges",
+            body=body,
+            idempotency_key=idempotency_key,
+        )
+
+        return parse_charge(payload)
+
+    def retrieve(self, charge_id: str) -> Charge:
+        payload = self._transport.request("GET", "/v1/charges/" + charge_id)
+
+        return parse_charge(payload)
+
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        status: Optional[str] = None,
+        query: Optional[str] = None,
+    ) -> ChargeList:
+        params: Dict[str, Any] = {}
+
+        if limit is not None:
+            params["limit"] = limit
+
+        if starting_after is not None:
+            params["starting_after"] = starting_after
+
+        if status is not None:
+            params["status"] = status
+
+        if query is not None:
+            params["q"] = query
+
+        payload = self._transport.request("GET", "/v1/charges", params=params)
+
+        return parse_charge_list(payload)

wishop/resources/payouts.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .._parsing import parse_payout, parse_payout_list
+from .._transport import Transport
+from ..types import Payout, PayoutList
+
+
+class Payouts:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def create(
+        self,
+        *,
+        amount: str,
+        currency: str,
+        recipient_phone: str,
+        idempotency_key: str,
+        reference: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Payout:
+        """Send money from your wallet to a customer's.
+
+        ``idempotency_key`` has no default, unlike everywhere else in this
+        client: a payout pushes money out, so a retry after a dropped
+        connection is indistinguishable from a second, deliberate payment.
+        Derive it from the thing being paid for and reuse it across retries — a
+        key generated per attempt defeats the mechanism entirely.
+
+        Three outcomes. The returned payout's ``status`` is ``SUCCEEDED`` (the
+        money moved) or ``PENDING`` (the wallet's answer was lost — it resolves
+        on its own and a webhook reports the outcome; never send a
+        replacement). A decline raises ``UnprocessableError`` and still records
+        a ``FAILED`` payout you can ``retrieve``.
+
+        There is no recipient name parameter: the name is resolved from the
+        wallet and returned on the payout.
+        """
+        body: Dict[str, Any] = {
+            "amount": amount,
+            "currency": currency,
+            "recipient_phone": recipient_phone,
+        }
+
+        if reference is not None:
+            body["reference"] = reference
+
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        payload = self._transport.request(
+            "POST",
+            "/v1/payouts",
+            body=body,
+            idempotency_key=idempotency_key,
+        )
+
+        return parse_payout(payload)
+
+    def retrieve(self, payout_id: str) -> Payout:
+        """Read one payout — how you check on a pending one, or read a decline."""
+        payload = self._transport.request("GET", "/v1/payouts/" + payout_id)
+
+        return parse_payout(payload)
+
+    def list(
+        self,
+        *,
+        limit: Optional[int] = None,
+        starting_after: Optional[str] = None,
+        status: Optional[str] = None,
+        currency: Optional[str] = None,
+    ) -> PayoutList:
+        params: Dict[str, Any] = {}
+
+        if limit is not None:
+            params["limit"] = limit
+
+        if starting_after is not None:
+            params["starting_after"] = starting_after
+
+        if status is not None:
+            params["status"] = status
+
+        if currency is not None:
+            params["currency"] = currency
+
+        payload = self._transport.request("GET", "/v1/payouts", params=params)
+
+        return parse_payout_list(payload)

wishop/resources/refunds.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .._parsing import parse_refund
+from .._transport import Transport
+from ..types import Refund
+
+
+class Refunds:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def create(
+        self,
+        charge_id: str,
+        *,
+        amount: Optional[str] = None,
+        reason: Optional[str] = None,
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Refund:
+        body: Dict[str, Any] = {}
+
+        if amount is not None:
+            body["amount"] = amount
+
+        if reason is not None:
+            body["reason"] = reason
+
+        if description is not None:
+            body["description"] = description
+
+        payload = self._transport.request(
+            "POST",
+            "/v1/charges/" + charge_id + "/refunds",
+            body=body,
+            idempotency_key=idempotency_key,
+        )
+
+        return parse_refund(payload)
+
+    def list(self, charge_id: str) -> List[Refund]:
+        payload = self._transport.request("GET", "/v1/charges/" + charge_id + "/refunds")
+
+        return [parse_refund(item) for item in payload.get("refunds", [])]

wishop/types.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+CHARGE_STATUS_INITIATED = "INITIATED"
+CHARGE_STATUS_OTP_SENT = "OTP_SENT"
+CHARGE_STATUS_PAID = "PAID"
+CHARGE_STATUS_FAILED = "FAILED"
+CHARGE_STATUS_EXPIRED = "EXPIRED"
+CHARGE_STATUS_REFUNDED = "REFUNDED"
+
+FAIL_REASON_INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS"
+FAIL_REASON_PIN_LOCKED = "PIN_LOCKED"
+FAIL_REASON_OTP_EXPIRED = "OTP_EXPIRED"
+FAIL_REASON_OTP_ATTEMPTS_EXCEEDED = "OTP_ATTEMPTS_EXCEEDED"
+FAIL_REASON_WALLET_NOT_FOUND = "WALLET_NOT_FOUND"
+FAIL_REASON_DECLINED = "DECLINED"
+FAIL_REASON_TIMEOUT = "TIMEOUT"
+FAIL_REASON_INTERNAL_ERROR = "INTERNAL_ERROR"
+
+FEE_BEARER_MERCHANT = "merchant"
+FEE_BEARER_CUSTOMER = "customer"
+
+REFUND_STATUS_PENDING = "pending"
+REFUND_STATUS_SUCCEEDED = "succeeded"
+REFUND_STATUS_FAILED = "failed"
+
+REFUND_REASON_REQUESTED_BY_CUSTOMER = "requested_by_customer"
+REFUND_REASON_DUPLICATE = "duplicate"
+REFUND_REASON_FRAUDULENT = "fraudulent"
+REFUND_REASON_OTHER = "other"
+
+EVENT_CHARGE_PAID = "charge.paid"
+EVENT_CHARGE_FAILED = "charge.failed"
+EVENT_CHARGE_EXPIRED = "charge.expired"
+EVENT_CHARGE_REFUNDED = "charge.refunded"
+
+EVENT_PAYOUT_CREATED = "payout.created"
+EVENT_PAYOUT_SUCCEEDED = "payout.succeeded"
+EVENT_PAYOUT_FAILED = "payout.failed"
+
+PAYOUT_STATUS_PENDING = "PENDING"
+PAYOUT_STATUS_SUCCEEDED = "SUCCEEDED"
+PAYOUT_STATUS_FAILED = "FAILED"
+
+# Payout-only fail reasons. FAIL_REASON_WALLET_NOT_FOUND is shared with charges.
+FAIL_REASON_INSUFFICIENT_MERCHANT_BALANCE = "INSUFFICIENT_MERCHANT_BALANCE"
+FAIL_REASON_RECIPIENT_INELIGIBLE = "RECIPIENT_INELIGIBLE"
+
+
+@dataclass(frozen=True)
+class Charge:
+    id: str
+    status: str
+    currency: str
+    amount: str
+    livemode: bool
+    created_at: datetime
+    order_id: Optional[str] = None
+    description: Optional[str] = None
+    fee_bearer: Optional[str] = None
+    fee: Optional[str] = None
+    net: Optional[str] = None
+    customer_debit_amount: Optional[str] = None
+    amount_refunded: Optional[str] = None
+    customer_phone_masked: Optional[str] = None
+    # "api" (created by you) or "app" (a customer paid your pay code in the app).
+    channel: Optional[str] = None
+    fail_reason: Optional[str] = None
+    return_url: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    expires_at: Optional[datetime] = None
+    confirmed_at: Optional[datetime] = None
+    pay_url: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Refund:
+    id: str
+    charge: str
+    amount: str
+    currency: str
+    status: str
+    livemode: bool
+    created_at: datetime
+    reason: Optional[str] = None
+    description: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ChargeList:
+    charges: List[Charge]
+    has_more: bool
+
+
+@dataclass(frozen=True)
+class Payout:
+    """Money sent from your wallet to a customer's.
+
+    ``status`` of ``PAYOUT_STATUS_PENDING`` does not mean "queued": the wallet's
+    answer was lost, so the money may or may not have moved. It resolves on its
+    own and a ``payout.succeeded`` or ``payout.failed`` webhook reports the
+    outcome. Never send a replacement payout for a pending one.
+    """
+
+    id: str
+    recipient_phone: str
+    currency: str
+    amount: str
+    # Charged on top of amount: your wallet is debited amount + fee.
+    fee: str
+    status: str
+    livemode: bool
+    created_at: datetime
+    recipient_name: Optional[str] = None
+    fail_reason: Optional[str] = None
+    reference: Optional[str] = None
+    # Values may be any JSON type, unlike a charge's string map.
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    completed_at: Optional[datetime] = None
+
+
+@dataclass(frozen=True)
+class PayoutList:
+    payouts: List[Payout]
+    has_more: bool
+
+
+@dataclass(frozen=True)
+class EventData:
+    """The object an event is about.
+
+    ``object`` says which — ``"charge"`` on charge.* events, ``"payout"`` on
+    payout.* ones — and only the matching field is set. ``charge`` became
+    optional in 1.1.0: a payout event carries none, and reading it
+    unconditionally used to raise KeyError.
+    """
+
+    object: str
+    charge: Optional[Charge] = None
+    refund: Optional[Refund] = None
+    payout: Optional[Payout] = None
+
+
+@dataclass(frozen=True)
+class Event:
+    id: str
+    type: str
+    api_version: str
+    created_at: datetime
+    livemode: bool
+    data: EventData

wishop/webhooks.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import List, Tuple, Union
+
+from ._parsing import parse_event
+from .errors import SignatureVerificationError
+from .types import Event
+
+DEFAULT_TOLERANCE = 300
+
+
+def construct_event(
+    payload: Union[bytes, str],
+    signature_header: str,
+    secret: str,
+    tolerance: int = DEFAULT_TOLERANCE,
+) -> Event:
+    raw = payload.encode("utf-8") if isinstance(payload, str) else payload
+    timestamp, signatures = _parse_signature_header(signature_header)
+
+    if tolerance > 0 and abs(time.time() - timestamp) > tolerance:
+        raise SignatureVerificationError("timestamp outside the tolerance window")
+
+    expected = hmac.new(
+        secret.encode("utf-8"),
+        str(timestamp).encode("utf-8") + b"." + raw,
+        hashlib.sha256,
+    ).hexdigest()
+
+    if not any(hmac.compare_digest(expected, signature) for signature in signatures):
+        raise SignatureVerificationError("no signature matched the signing secret")
+
+    try:
+        decoded = json.loads(raw)
+    except ValueError as exc:
+        raise SignatureVerificationError("payload is not valid JSON") from exc
+
+    return parse_event(decoded)
+
+
+def _parse_signature_header(header: str) -> Tuple[int, List[str]]:
+    timestamp = None
+    signatures = []
+
+    for part in header.split(","):
+        key, separator, value = part.strip().partition("=")
+
+        if not separator:
+            continue
+
+        if key == "t":
+            try:
+                timestamp = int(value)
+            except ValueError:
+                raise SignatureVerificationError("malformed timestamp") from None
+        elif key == "v1" and value:
+            signatures.append(value)
+
+    if timestamp is None:
+        raise SignatureVerificationError("no timestamp in signature header")
+
+    if not signatures:
+        raise SignatureVerificationError("no v1 signature in signature header")
+
+    return timestamp, signatures

wishop-1.2.0.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.5
+Name: wishop
+Version: 1.2.0
+Summary: The official Python client for the Wishop API
+Project-URL: Documentation, https://developers.wishopht.com
+Project-URL: Source, https://github.com/wishopht/wishop-python
+License: MIT License
+        
+        Copyright (c) 2026 Wishop
+        
+        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.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Wishop Python
+
+The official Python client for the [Wishop API](https://developers.wishopht.com).
+
+Create charges, send customers to a hosted checkout page, refund them, and verify webhooks.
+
+## Install
+
+```bash
+pip install wishop
+```
+
+Requires Python 3.9 or later.
+
+## Quickstart
+
+```python
+import os
+
+from wishop import Wishop
+
+client = Wishop(os.environ["WISHOP_SECRET_KEY"])
+
+charge = client.charges.create(
+    amount="1500.00",
+    currency="HTG",
+    order_id="order_1042",
+    description="Two large coffees",
+    return_url="https://yourstore.com/orders/1042/complete",
+    metadata={"cart_id": "c_88213"},
+)
+
+print(charge.pay_url)
+```
+
+Send the customer to `charge.pay_url`. It is returned on create only, so persist it with the order.
+
+When the payment reaches a terminal state, Wishop sends a webhook and returns the customer to your `return_url`. Confirm the outcome from the webhook or by retrieving the charge — never from the redirect alone.
+
+## Configuration
+
+```python
+client = Wishop(
+    os.environ["WISHOP_SECRET_KEY"],
+    timeout=10.0,
+    session=my_session,
+    base_url="http://localhost:8080",
+)
+```
+
+| Argument | Default | Notes |
+| --- | --- | --- |
+| `timeout` | `30.0` | Seconds, applied to every request |
+| `session` | a new `requests.Session` | Supply your own for proxies, retries at the transport layer, or custom TLS |
+| `base_url` | `https://gatewayapi.wishopht.com` | For pointing at a mock server in your own tests |
+
+Test and live mode are selected by the key, not by configuration. A `sk_test_` key reaches test data; a `sk_live_` key reaches live data.
+
+The client is synchronous. From an async framework, run calls in a worker thread so the event loop is not blocked:
+
+```python
+charge = await asyncio.to_thread(client.charges.create, amount="1500.00", currency="HTG")
+```
+
+## Charges
+
+```python
+charge = client.charges.create(amount="1500.00", currency="HTG")
+charge = client.charges.retrieve("ch_3kQ8xR2mVn7pLdYt")
+page = client.charges.list(status="PAID", limit=100)
+```
+
+`list` returns one page. Pass the id of the last charge as `starting_after` while `has_more` is true:
+
+```python
+def all_charges(client, status=None):
+    starting_after = None
+
+    while True:
+        page = client.charges.list(limit=100, status=status, starting_after=starting_after)
+
+        for charge in page.charges:
+            yield charge
+
+        if not page.has_more:
+            return
+
+        starting_after = page.charges[-1].id
+```
+
+Search across charge id and order id with `query`, which maps to the API's `q` parameter.
+
+## Refunds
+
+```python
+refund = client.refunds.create(
+    "ch_3kQ8xR2mVn7pLdYt",
+    amount="500.00",
+    reason="requested_by_customer",
+)
+
+refunds = client.refunds.list("ch_3kQ8xR2mVn7pLdYt")
+```
+
+Omit `amount` to refund everything still refundable. Refund lists are not paginated.
+
+## Payouts
+
+Sends money from your wallet to a customer's — payroll, marketplace settlements, rewards.
+
+```python
+payout = client.payouts.create(
+    amount="150.00",
+    currency="HTG",
+    recipient_phone="+50931234567",
+    reference="June payroll",
+    idempotency_key=f"payroll-2026-06-{employee.id}",
+)
+
+payouts = client.payouts.list(status="FAILED")
+one = client.payouts.retrieve("po_7Hn2vB9xQm4tRkLw")
+```
+
+`idempotency_key` has **no default** here, unlike everywhere else in this client: a payout pushes money out, so an un-keyed retry after a dropped connection is indistinguishable from a second payment. Your wallet is debited `amount + fee`.
+
+Three outcomes, and the middle one is the one to handle:
+
+```python
+if payout.status == wishop.PAYOUT_STATUS_SUCCEEDED:
+    ...  # the money moved
+elif payout.status == wishop.PAYOUT_STATUS_PENDING:
+    # The wallet's answer was lost — the money may or may not have moved.
+    # It resolves on its own and a webhook reports the outcome.
+    # Never send a replacement; retry with the SAME key if you must.
+    ...
+```
+
+A decline raises `UnprocessableError` and still records a `FAILED` payout you can `retrieve` — unlike a rejected refund, which leaves nothing behind.
+
+## Money
+
+Amounts are strings, never numbers, and every field that holds money is a string: `amount`, `fee`, `net`, `customer_debit_amount`, `amount_refunded`. Parse them with `Decimal`, never a float.
+
+```python
+from decimal import Decimal
+
+amount = Decimal(charge.amount)
+```
+
+## Idempotency
+
+Pass a key on charge and refund creation so a retry after a timeout cannot charge twice:
+
+```python
+charge = client.charges.create(
+    amount="1500.00",
+    currency="HTG",
+    idempotency_key=f"charge-{order.id}-{order.payment_attempt}",
+)
+```
+
+On charges and refunds nothing is sent unless you pass it. **Payouts are the exception: `idempotency_key` is a required keyword argument**, so omitting it is a `TypeError` rather than a rejected request.
+
+Derive a charge key from the payment *attempt*, not the order — reusing an order id replays the previous failure instead of creating the charge a retrying customer needs. Derive a payout key the opposite way, from the payment itself, and reuse it across retries: a fresh key on a payout retry sends a second payment. Keys are remembered for 24 hours.
+
+## Errors
+
+Every failure raises a typed exception:
+
+```python
+from wishop import RateLimitError, UnprocessableError, WishopError
+
+try:
+    charge = client.charges.create(amount="1500.00", currency="HTG")
+except RateLimitError as exc:
+    time.sleep(exc.retry_after or 1)
+except UnprocessableError as exc:
+    log.warning(exc.message)
+except WishopError as exc:
+    log.error("wishop failed with %s", exc.status_code)
+```
+
+| Exception | Status | Cause |
+| --- | --- | --- |
+| `ValidationError` | 400 | Malformed body, invalid amount or currency, metadata over the limits |
+| `AuthenticationError` | 401 | Missing, malformed, unknown, or revoked key |
+| `PermissionError` | 403 | Live key from an address that is not whitelisted |
+| `NotFoundError` | 404 | No charge, refund or payout with that id in this mode; or no wallet for a payout recipient's phone |
+| `ConflictError` | 409 | Idempotency key still in flight, charge no longer payable, or wallet not provisioned for live payouts |
+| `ChargeExpiredError` | 410 | Charge expired |
+| `PayloadTooLargeError` | 413 | Upload too large |
+| `UnprocessableError` | 422 | Currency not enabled, charge not refundable, refund exceeds remaining, wallet declined, or a payout declined for balance or recipient |
+| `RateLimitError` | 429 | Rate limit exceeded; carries `retry_after` in seconds |
+| `APIError` | 5xx and anything unmapped | Failure on the gateway side |
+| `APIConnectionError` | — | The request never completed: DNS, TLS, connection reset, or timeout |
+
+All of them subclass `WishopError`, which carries `.status_code` and `.message`.
+
+`PermissionError` shadows the builtin of the same name when imported bare — import it as `from wishop import PermissionError as WishopPermissionError` if that matters in your module.
+
+`.message` is prose and its wording can change — branch on the exception type or `.status_code`, never on the text.
+
+The client does not retry. `ConflictError`, `RateLimitError`, and `APIError` are safe to retry with backoff and the same idempotency key; nothing else is.
+
+## Payment failures
+
+A failed payment is not an exception — the call succeeded, the payment didn't. Read `status` and `fail_reason`:
+
+```python
+if charge.status == "FAILED":
+    show(EXPLANATIONS.get(charge.fail_reason, "The payment could not be completed."))
+```
+
+| `fail_reason` | Meaning |
+| --- | --- |
+| `INSUFFICIENT_FUNDS` | Wallet balance did not cover the payment |
+| `PIN_LOCKED` | Wallet locked after repeated incorrect PINs |
+| `OTP_EXPIRED` | One-time code expired before use |
+| `OTP_ATTEMPTS_EXCEEDED` | Too many incorrect one-time codes |
+| `WALLET_NOT_FOUND` | No wallet for that phone number |
+| `DECLINED` | Wallet refused the payment |
+| `TIMEOUT` | Confirmation timed out |
+| `INTERNAL_ERROR` | Failure on our side |
+
+Keep a default branch — new reasons can be added, and `fail_reason` is a plain string so an unknown value arrives intact rather than failing to parse.
+
+## Webhooks
+
+Verification needs the body **exactly as received**. `request.json` and `request.get_json()` will not do — they hand you a parsed object, and re-serializing it changes whitespace and key order so the signature will never match.
+
+Flask:
+
+```python
+from wishop import SignatureVerificationError, construct_event
+
+@app.post("/webhooks/wishop")
+def wishop_webhook():
+    try:
+        event = construct_event(
+            request.get_data(),
+            request.headers.get("X-Wishop-Signature", ""),
+            os.environ["WISHOP_WEBHOOK_SECRET"],
+        )
+    except SignatureVerificationError:
+        return "", 400
+
+    if events.seen(request.headers["X-Webhook-Id"]):
+        return "", 200
+
+    if event.type == "charge.paid":
+        fulfil(event.data.charge)
+    elif event.type == "charge.failed":
+        notify_failure(event.data.charge)
+    elif event.type == "charge.expired":
+        release_stock(event.data.charge)
+    elif event.type == "charge.refunded":
+        record_refund(event.data.refund)
+    elif event.type == "payout.succeeded":
+        mark_payout_sent(event.data.payout)
+    elif event.type == "payout.failed":
+        mark_payout_failed(event.data.payout)
+
+    return "", 200
+```
+
+Django uses `request.body`; FastAPI uses `await request.body()`.
+
+`construct_event` rejects a stale timestamp, an altered body, and a signature that does not match. It accepts a match on any `v1` value, which is what keeps events flowing during a secret rotation. The default tolerance is 300 seconds:
+
+```python
+event = construct_event(body, signature, secret, tolerance=60)
+```
+
+Delivery is at-least-once, so deduplicate on the `X-Webhook-Id` header, which is stable across retries. Record it in the same transaction as the work it triggers. Respond `2xx` once the event is durably recorded and queue anything slow — you have about ten seconds per attempt.
+
+`event.data.refund` is set only on `charge.refunded`. A partial refund leaves the charge `PAID`; read `amount_refunded`.
+
+`event.data.charge` is `None` on `payout.*` events and `event.data.payout` is `None` on `charge.*` ones — `event.data.object` says which you have.
+
+## Testing
+
+Test mode uses `sk_test_` keys against the same host. The outcome is chosen by a phone number — the one the customer enters for a charge, the recipient's for a payout. The two use different tables; `+50900000006` is how you exercise a pending payout. See [test phone numbers](https://developers.wishopht.com/testing/test-phone-numbers).
+
+To test your own code against this client, point it at a local server:
+
+```python
+client = Wishop("sk_test_key", base_url="http://localhost:8080")
+```
+
+## Reference
+
+Field-by-field documentation for the charge, refund, payout, and event objects lives at [developers.wishopht.com](https://developers.wishopht.com).
+
+## License
+
+MIT

wishop-1.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+wishop/__init__.py,sha256=Rqm3eVS1WIY_D_i_1QUqsyLyZCrBMjnpeJFzBEGPKQw,3132
+wishop/_parsing.py,sha256=AUa-YYlqF5BMEX0Aijr7b7ukM0zxjOKoCxCAM8ctU60,4000
+wishop/_transport.py,sha256=2AmuJpJi_e19Tbj6ayPdGzteTR4kEBXWsojz19x0DHk,2039
+wishop/client.py,sha256=Ge0ZFCN9-n19lIZAkoG_RZ_5b09s4q7oaXPgJjw1EpU,856
+wishop/errors.py,sha256=Aww-JVUkx0KpT-JZhnPTZbvQ7IwOZqmrAf2e7gP4eE8,1539
+wishop/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wishop/types.py,sha256=-IKS6RUczycMi2XskgXTX6g-z2OC6mimb0WcHoBZ6oA,4418
+wishop/webhooks.py,sha256=WDzLbd5HajrYTY6DzUCa9ors73IcIH6gunGVKL6Y1nA,1976
+wishop/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wishop/resources/charges.py,sha256=VE3pPdHinXJiCiyA0AoXSErtcSYE3djVyMv5VctF_NY,2188
+wishop/resources/payouts.py,sha256=ExuRWj_RPkpFqvkE0zX2MkgRliz_UpIPA26YrsBdBNY,2935
+wishop/resources/refunds.py,sha256=84BIBEmhV2JxDZf2_XZUElFWFjr7c2t1yXdrGa9wUig,1241
+wishop-1.2.0.dist-info/METADATA,sha256=kPO-HngjTvvOCCTK99qsJdG4bK0f_YNkXXhCFM79O84,13076
+wishop-1.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+wishop-1.2.0.dist-info/licenses/LICENSE,sha256=GRjrQypCpUeMjH5aWF3-Z3oZu17mnELyQ55TQ9mzTKE,1063
+wishop-1.2.0.dist-info/RECORD,,

wishop-1.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

wishop-1.2.0.dist-info/licenses/LICENSE

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