fqris 0.1.0__py3-none-any.whl

fqris/__init__.py

@@ -0,0 +1,19 @@
+from ._client import Client
+from ._errors import FQrisError, PaymentNotPaidError, SignatureVerificationError
+from ._http import VERSION as __version__
+from ._object import FQrisObject
+from ._transport import HttpClient, HttpResponse, TransportError
+from ._webhook import Webhook
+
+__all__ = [
+    "Client",
+    "FQrisError",
+    "FQrisObject",
+    "HttpClient",
+    "HttpResponse",
+    "PaymentNotPaidError",
+    "SignatureVerificationError",
+    "TransportError",
+    "Webhook",
+    "__version__",
+]

fqris/_client.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+from ._http import Http
+from ._transport import HttpClient, UrllibClient
+from .resources.customers import Customers
+from .resources.events import Events
+from .resources.invoices import Invoices
+from .resources.payment_links import PaymentLinks
+from .resources.payments import Payments
+from .resources.refunds import Refunds
+from .resources.sandbox import Sandbox
+from .resources.webhook_endpoints import WebhookEndpoints
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.fqris.id",
+        max_retries: int = 2,
+        timeout: float = 30.0,
+        http_client: HttpClient | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if not isinstance(api_key, str) or not api_key.startswith(
+            ("fq_live_", "fq_test_")
+        ):
+            raise ValueError("api_key harus diawali fq_live_ atau fq_test_.")
+        self._http = Http(
+            api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+            client=http_client or UrllibClient(),
+            sleep=sleep,
+        )
+        self.payments = Payments(self._http)
+        self.refunds = Refunds(self._http)
+        self.sandbox = Sandbox(self._http)
+        self.customers = Customers(self._http)
+        self.payment_links = PaymentLinks(self._http)
+        self.invoices = Invoices(self._http)
+        self.webhook_endpoints = WebhookEndpoints(self._http)
+        self.events = Events(self._http)

fqris/_errors.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ._object import FQrisObject
+
+
+class FQrisError(Exception):
+    """Error dari API FQris, atau dari SDK sendiri (status 0 untuk TIMEOUT/NETWORK_ERROR)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        type: str,
+        code: str,
+        param: str | None = None,
+        request_id: str | None = None,
+        doc_url: str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.type = type
+        self.code = code
+        self.param = param
+        self.request_id = request_id
+        self.doc_url = doc_url
+        self.headers: Mapping[str, str] = headers or {}
+
+
+class PaymentNotPaidError(Exception):
+    """Payment belum/tidak lagi `paid` (mis. refunded, pending, expired)."""
+
+    def __init__(self, payment: FQrisObject) -> None:
+        super().__init__(
+            f"Payment {payment.get('id')} belum lunas (status: {payment.get('status')})."
+        )
+        self.payment = payment
+
+
+class SignatureVerificationError(Exception):
+    """Webhook tidak bisa diverifikasi: header, timestamp, signature, atau body tidak valid."""

fqris/_http.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import json
+import math
+import platform
+import random
+import uuid
+from collections.abc import Mapping
+from typing import Any, Callable
+from urllib.parse import urlencode
+
+from ._errors import FQrisError
+from ._object import FQrisObject
+from ._transport import HttpClient, HttpResponse, TransportError
+
+# Harus sama dengan pyproject.toml (dijaga oleh tests/test_version.py).
+VERSION = "0.1.0"
+
+MAX_RETRY_AFTER_S = 60.0
+
+
+def _backoff(n: int) -> float:
+    return float(min(8.0, 0.5 * 2**n) * random.uniform(0.8, 1.2))
+
+
+def _scalar(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return str(v)
+
+
+def build_query(query: Mapping[str, Any] | None) -> str:
+    if not query:
+        return ""
+    pairs: list[tuple[str, str]] = []
+    for k, v in query.items():
+        if v is None:
+            continue
+        if isinstance(v, (list, tuple)):
+            pairs += [(f"{k}[]", _scalar(i)) for i in v if i is not None]
+        elif isinstance(v, Mapping):
+            pairs += [
+                (f"{k}[{sk}]", _scalar(sv)) for sk, sv in v.items() if sv is not None
+            ]
+        else:
+            pairs.append((k, _scalar(v)))
+    return f"?{urlencode(pairs)}" if pairs else ""
+
+
+def _to_error(res: HttpResponse) -> FQrisError:
+    header_rid = res.headers.get("x-request-id")
+    try:
+        parsed = json.loads(res.body)
+    except ValueError:
+        parsed = None
+    e = parsed.get("error") if isinstance(parsed, dict) else None
+    if isinstance(e, dict):
+
+        def s(key: str) -> str | None:
+            v = e.get(key)
+            return v if isinstance(v, str) else None
+
+        return FQrisError(
+            str(e.get("message") or f"HTTP {res.status}"),
+            status=res.status,
+            type=str(e.get("type") or "api_error"),
+            code=str(e.get("code") or "UNKNOWN_ERROR"),
+            param=s("param"),
+            request_id=s("request_id") or header_rid,
+            doc_url=s("doc_url"),
+            headers=res.headers,
+        )
+    return FQrisError(
+        f"HTTP {res.status}: respons bukan JSON error FQris",
+        status=res.status,
+        type="api_error",
+        code="INTERNAL_ERROR" if res.status >= 500 else "INVALID_RESPONSE",
+        request_id=header_rid,
+        headers=res.headers,
+    )
+
+
+class Http:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str,
+        max_retries: int,
+        timeout: float,
+        client: HttpClient,
+        sleep: Callable[[float], None],
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._client = client
+        self._sleep = sleep
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        *,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+    ) -> FQrisObject | None:
+        # POST tanpa field tetap mengirim `{}`; GET/DELETE tidak mengirim body.
+        if method == "POST" and body is None:
+            body = {}
+        res = self._send(method, path, body, query, idempotency_key, request_id)
+        if not res.body:
+            return None
+        try:
+            parsed = json.loads(res.body)
+        except ValueError:
+            parsed = None
+        if not isinstance(parsed, dict):
+            raise FQrisError(
+                "Respons sukses bukan objek JSON yang valid",
+                status=res.status,
+                type="api_error",
+                code="INVALID_RESPONSE",
+                request_id=res.headers.get("x-request-id"),
+                headers=res.headers,
+            )
+        return FQrisObject.construct_from(parsed)
+
+    def request_raw(self, path: str, query: Mapping[str, Any] | None = None) -> bytes:
+        return self._send("GET", path, None, query, None, None).body
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        body: Mapping[str, Any] | None,
+        query: Mapping[str, Any] | None,
+        idempotency_key: str | None,
+        request_id: str | None,
+    ) -> HttpResponse:
+        url = f"{self._base_url}{path}{build_query(query)}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"fqris-python/{VERSION} python/{platform.python_version()}",
+        }
+        # Kunci kosong/terlalu panjang (PRD 10.1) ditolak di sini; kunci kosong membuat retry bisa menggandakan payment.
+        if idempotency_key is not None and not 1 <= len(idempotency_key) <= 255:
+            raise ValueError("idempotency_key harus string 1-255 karakter.")
+        # Kunci dibuat SEKALI sebelum percobaan pertama: retry tidak boleh membuat payment ganda.
+        if method == "POST":
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        if request_id:
+            headers["X-Request-Id"] = request_id
+        payload = None if body is None else json.dumps(body).encode()
+        # Fastify menolak Content-Type JSON tanpa body (400).
+        if payload is not None:
+            headers["Content-Type"] = "application/json"
+
+        attempt = 0
+        while True:
+            can_retry = attempt < self._max_retries
+            try:
+                res = self._client.send(method, url, headers, payload, self._timeout)
+            except TransportError as e:
+                if can_retry:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise FQrisError(
+                    f"Request melebihi {self._timeout} detik"
+                    if e.timed_out
+                    else f"Gagal menghubungi FQris: {e}",
+                    status=0,
+                    type="api_error",
+                    code="TIMEOUT" if e.timed_out else "NETWORK_ERROR",
+                ) from e
+            if 200 <= res.status < 300:
+                return res
+            if can_retry and (res.status == 429 or res.status >= 500):
+                delay = _backoff(attempt)
+                if res.status == 429:
+                    try:
+                        ra = float(res.headers.get("retry-after", "").strip())
+                    except ValueError:
+                        ra = math.nan
+                    # Server minta menunggu terlalu lama: jangan menggantung, serahkan ke pemanggil.
+                    if ra > MAX_RETRY_AFTER_S:
+                        raise _to_error(res)
+                    if math.isfinite(ra) and ra >= 0:
+                        delay = ra
+                self._sleep(delay)
+                attempt += 1
+                continue
+            raise _to_error(res)

fqris/_object.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+def _wrap(v: Any) -> Any:
+    if isinstance(v, dict):
+        return FQrisObject.construct_from(v)
+    if isinstance(v, list):
+        return [_wrap(i) for i in v]
+    return v
+
+
+class FQrisObject(dict[str, Any]):
+    """dict dengan akses atribut bersarang (`p.metadata["user_id"]`, `event.data.object.id`).
+
+    Kunci yang bentrok dengan metode dict (`items`, `keys`, `values`, ...) dibaca lewat `obj["items"]`.
+    """
+
+    @classmethod
+    def construct_from(cls, values: Mapping[str, Any]) -> FQrisObject:
+        return cls({k: _wrap(v) for k, v in values.items()})
+
+    def __getattr__(self, name: str) -> Any:
+        # Dunder harus AttributeError agar pickle/copy tidak rusak.
+        if name.startswith("__"):
+            raise AttributeError(name)
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name) from None

fqris/_pagination.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Callable
+
+from ._object import FQrisObject
+
+
+def paginate(fetch_page: Callable[[str | None], FQrisObject]) -> Iterator[FQrisObject]:
+    """Mengikuti `next_cursor` (dikirim sebagai `starting_after`) sampai `has_more` false."""
+    cursor: str | None = None
+    while True:
+        page = fetch_page(cursor)
+        yield from page.data
+        # next_cursor kosong walau has_more true: berhenti, jangan mengulang halaman yang sama selamanya.
+        if not page.get("has_more") or not page.get("next_cursor"):
+            return
+        cursor = page.next_cursor

fqris/_transport.py

@@ -0,0 +1,84 @@
+"""Lapisan transport: antarmuka HttpClient dan implementasi bawaan berbasis urllib."""
+
+from __future__ import annotations
+
+import http.client
+import socket
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from dataclasses import dataclass
+from email.message import Message
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    status: int
+    headers: Mapping[str, str]  # nama header huruf kecil
+    body: bytes
+
+
+class TransportError(Exception):
+    """Kegagalan jaringan (bukan respons HTTP); status non-2xx BUKAN TransportError."""
+
+    def __init__(self, message: str, *, timed_out: bool) -> None:
+        super().__init__(message)
+        self.timed_out = timed_out
+
+
+class HttpClient(Protocol):
+    def send(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        timeout: float,
+    ) -> HttpResponse: ...
+
+
+def _lower(headers: Message[str, str]) -> Mapping[str, str]:
+    return {k.lower(): v for k, v in headers.items()}
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # Jangan ikuti 3xx: urllib menyalin Authorization dan Idempotency-Key ke target redirect.
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+class UrllibClient:
+    """Implementasi bawaan tanpa dependensi."""
+
+    def send(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        timeout: float,
+    ) -> HttpResponse:
+        req = urllib.request.Request(
+            url, data=body, headers=dict(headers), method=method
+        )
+        try:
+            try:
+                with _OPENER.open(req, timeout=timeout) as r:
+                    return HttpResponse(r.status, _lower(r.headers), r.read())
+            except urllib.error.HTTPError as e:
+                # Status non-2xx adalah respons, bukan kegagalan transport.
+                try:
+                    return HttpResponse(e.code, _lower(e.headers), e.read())
+                finally:
+                    e.close()
+        except urllib.error.URLError as e:
+            timed_out = isinstance(e.reason, (socket.timeout, TimeoutError))
+            raise TransportError(str(e.reason), timed_out=timed_out) from e
+        except (socket.timeout, TimeoutError) as e:
+            raise TransportError(str(e) or "timeout", timed_out=True) from e
+        except (OSError, http.client.HTTPException) as e:
+            raise TransportError(str(e), timed_out=False) from e

fqris/_webhook.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import math
+import re
+import time
+from typing import Any
+
+from ._errors import SignatureVerificationError
+from ._object import FQrisObject
+
+_HEX = re.compile(r"[0-9a-fA-F]+")
+_DIGITS = re.compile(r"[0-9]+")
+
+
+def _parse_header(header: Any) -> tuple[int, list[str]] | None:
+    if not isinstance(header, str):
+        return None
+    t: int | None = None
+    v1: list[str] = []
+    for part in header.split(","):
+        k, _, v = part.partition("=")
+        k, v = k.strip(), v.strip()
+        if k == "t" and _DIGITS.fullmatch(v):
+            t = int(v)
+        elif k == "v1" and _HEX.fullmatch(v):
+            v1.append(v.lower())
+    return None if t is None or not v1 else (t, v1)
+
+
+class Webhook:
+    """Verifikasi header `FQris-Signature` lalu parse body menjadi event."""
+
+    DEFAULT_TOLERANCE = 300
+
+    @staticmethod
+    def construct_event(
+        payload: bytes | str,
+        sig_header: str | None,
+        secret: str,
+        tolerance: int = DEFAULT_TOLERANCE,
+        now: int | None = None,
+    ) -> FQrisObject:
+        if not isinstance(payload, (bytes, bytearray, str)):
+            raise SignatureVerificationError(
+                "Payload webhook harus berupa raw body (str atau bytes), bukan hasil parse "
+                "(dict). Pakai request.body (Django) atau request.get_data() (Flask), "
+                "bukan request.json."
+            )
+        if not isinstance(secret, str) or secret.strip() == "":
+            raise SignatureVerificationError(
+                "Secret webhook kosong. Isi FQRIS webhook secret dari dashboard."
+            )
+        parsed = _parse_header(sig_header)
+        if parsed is None:
+            raise SignatureVerificationError("Header FQris-Signature hilang atau formatnya salah.")
+        t, v1 = parsed
+
+        current = int(time.time()) if now is None else now
+        # isfinite menolak inf dan NaN (inf mematikan proteksi replay), seperti SDK Node.
+        if not (math.isfinite(tolerance) and tolerance >= 0) or not abs(current - t) <= tolerance:
+            raise SignatureVerificationError(
+                "Timestamp signature di luar batas toleransi, atau tolerance tidak valid."
+            )
+
+        body = payload.encode("utf-8") if isinstance(payload, str) else bytes(payload)
+        expected = hmac.new(secret.encode("utf-8"), f"{t}.".encode() + body, hashlib.sha256)
+        digest = expected.hexdigest()
+        if not any(hmac.compare_digest(c, digest) for c in v1):
+            raise SignatureVerificationError("Signature webhook tidak cocok.")
+
+        try:
+            # errors="replace": signature sudah dicek atas byte mentah, sama seperti SDK Node.
+            data = json.loads(body.decode("utf-8", errors="replace"))
+        except ValueError:
+            raise SignatureVerificationError("Body webhook bukan JSON yang valid.") from None
+        if not isinstance(data, dict):
+            raise SignatureVerificationError("Body webhook harus berupa objek JSON.")
+        return FQrisObject.construct_from(data)

fqris/resources/_base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from .._http import Http
+from .._object import FQrisObject
+
+
+def seg(id: str) -> str:
+    """Satu segmen path dari id masukan pemanggil: di-encode, dan tolak yang bisa membelokkan request."""
+    if not isinstance(id, str) or id in ("", ".", ".."):
+        raise ValueError(f"ID tidak valid: {id!r}")
+    return quote(id, safe="")
+
+
+def need(res: FQrisObject | None) -> FQrisObject:
+    # Endpoint ini selalu membalas objek; body kosong (204) berarti server menyimpang dari kontrak.
+    if res is None:
+        raise ValueError("Respons kosong dari API.")
+    return res
+
+
+class Resource:
+    def __init__(self, http: Http) -> None:
+        self._http = http

fqris/resources/customers.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from .._object import FQrisObject
+from .._pagination import paginate
+from ._base import Resource, need, seg
+
+
+class Customers(Resource):
+    def create(
+        self,
+        *,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+        **params: Any,
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                "/v1/customers",
+                params,
+                idempotency_key=idempotency_key,
+                request_id=request_id,
+            )
+        )
+
+    def retrieve(self, id: str) -> FQrisObject:
+        return need(self._http.request("GET", f"/v1/customers/{seg(id)}"))
+
+    def update(self, id: str, **params: Any) -> FQrisObject:
+        return need(self._http.request("PATCH", f"/v1/customers/{seg(id)}", params))
+
+    def list(self, **params: Any) -> FQrisObject:
+        return need(self._http.request("GET", "/v1/customers", query=params))
+
+    def list_all(self, **params: Any) -> Iterator[FQrisObject]:
+        return paginate(
+            lambda cursor: self.list(**{**params, "starting_after": cursor})
+        )

fqris/resources/events.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from .._object import FQrisObject
+from .._pagination import paginate
+from ._base import Resource, need, seg
+
+
+class Events(Resource):
+    def retrieve(self, id: str) -> FQrisObject:
+        return need(self._http.request("GET", f"/v1/events/{seg(id)}"))
+
+    def list(self, **params: Any) -> FQrisObject:
+        return need(self._http.request("GET", "/v1/events", query=params))
+
+    def list_all(self, **params: Any) -> Iterator[FQrisObject]:
+        return paginate(
+            lambda cursor: self.list(**{**params, "starting_after": cursor})
+        )
+
+    def resend(
+        self,
+        id: str,
+        *,
+        idempotency_key: str | None = None,
+        **params: Any,
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/events/{seg(id)}/resend",
+                params,
+                idempotency_key=idempotency_key,
+            )
+        )

fqris/resources/invoices.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from .._object import FQrisObject
+from .._pagination import paginate
+from ._base import Resource, need, seg
+
+
+class Invoices(Resource):
+    def create(
+        self,
+        *,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+        **params: Any,
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                "/v1/invoices",
+                params,
+                idempotency_key=idempotency_key,
+                request_id=request_id,
+            )
+        )
+
+    def retrieve(self, id: str) -> FQrisObject:
+        return need(self._http.request("GET", f"/v1/invoices/{seg(id)}"))
+
+    def update(self, id: str, **params: Any) -> FQrisObject:
+        return need(self._http.request("PATCH", f"/v1/invoices/{seg(id)}", params))
+
+    def list(self, **params: Any) -> FQrisObject:
+        return need(self._http.request("GET", "/v1/invoices", query=params))
+
+    def list_all(self, **params: Any) -> Iterator[FQrisObject]:
+        return paginate(
+            lambda cursor: self.list(**{**params, "starting_after": cursor})
+        )
+
+    def delete(self, id: str) -> FQrisObject | None:
+        """Hapus draf; server membalas 204 tanpa body (hasil `None`)."""
+        return self._http.request("DELETE", f"/v1/invoices/{seg(id)}")
+
+    def pdf(self, id: str) -> bytes:
+        return self._http.request_raw(f"/v1/invoices/{seg(id)}/pdf")
+
+    def finalize(self, id: str, *, idempotency_key: str | None = None) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/invoices/{seg(id)}/finalize",
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def void(self, id: str, *, idempotency_key: str | None = None) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/invoices/{seg(id)}/void",
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def send(self, id: str, *, idempotency_key: str | None = None) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/invoices/{seg(id)}/send",
+                idempotency_key=idempotency_key,
+            )
+        )

fqris/resources/payment_links.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from .._object import FQrisObject
+from .._pagination import paginate
+from ._base import Resource, need, seg
+
+
+class PaymentLinks(Resource):
+    def create(
+        self,
+        *,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+        **params: Any,
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                "/v1/payment-links",
+                params,
+                idempotency_key=idempotency_key,
+                request_id=request_id,
+            )
+        )
+
+    def retrieve(self, id: str) -> FQrisObject:
+        return need(self._http.request("GET", f"/v1/payment-links/{seg(id)}"))
+
+    def update(self, id: str, **params: Any) -> FQrisObject:
+        return need(self._http.request("PATCH", f"/v1/payment-links/{seg(id)}", params))
+
+    def list(self, **params: Any) -> FQrisObject:
+        return need(self._http.request("GET", "/v1/payment-links", query=params))
+
+    def list_all(self, **params: Any) -> Iterator[FQrisObject]:
+        return paginate(
+            lambda cursor: self.list(**{**params, "starting_after": cursor})
+        )
+
+    def archive(self, id: str, *, idempotency_key: str | None = None) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/payment-links/{seg(id)}/archive",
+                idempotency_key=idempotency_key,
+            )
+        )

fqris/resources/payments.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from .._errors import PaymentNotPaidError
+from .._object import FQrisObject
+from .._pagination import paginate
+from ._base import Resource, need, seg
+
+
+class Payments(Resource):
+    def create(
+        self,
+        *,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+        **params: Any,
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                "/v1/payments",
+                params,
+                idempotency_key=idempotency_key,
+                request_id=request_id,
+            )
+        )
+
+    def retrieve(self, id: str, *, expand: Sequence[str] | None = None) -> FQrisObject:
+        return need(
+            self._http.request(
+                "GET", f"/v1/payments/{seg(id)}", query={"expand": expand}
+            )
+        )
+
+    def list(self, **params: Any) -> FQrisObject:
+        return need(self._http.request("GET", "/v1/payments", query=params))
+
+    def list_all(self, **params: Any) -> Iterator[FQrisObject]:
+        return paginate(
+            lambda cursor: self.list(**{**params, "starting_after": cursor})
+        )
+
+    def cancel(self, id: str, *, idempotency_key: str | None = None) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/payments/{seg(id)}/cancel",
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def events(self, id: str) -> FQrisObject:
+        return need(self._http.request("GET", f"/v1/payments/{seg(id)}/events"))
+
+    def qr(self, id: str, format: str = "png") -> bytes:
+        if format not in ("png", "svg"):
+            raise ValueError("format harus 'png' atau 'svg'.")
+        return self._http.request_raw(f"/v1/payments/{seg(id)}/qr.{format}")
+
+    def retrieve_and_assert_paid(self, id: str) -> FQrisObject:
+        """Lolos hanya bila status `paid`; refunded/partially_refunded/dll melempar agar tidak dikredit ulang."""
+        payment = self.retrieve(id)
+        if payment.get("status") != "paid":
+            raise PaymentNotPaidError(payment)
+        return payment

fqris/resources/refunds.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._object import FQrisObject
+from ._base import Resource, need, seg
+
+
+class Refunds(Resource):
+    def create(
+        self,
+        payment_id: str,
+        *,
+        idempotency_key: str | None = None,
+        **params: Any,
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/payments/{seg(payment_id)}/refunds",
+                params,
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def list(self, payment_id: str) -> FQrisObject:
+        return need(
+            self._http.request("GET", f"/v1/payments/{seg(payment_id)}/refunds")
+        )
+
+    def void(self, id: str, *, idempotency_key: str | None = None) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST", f"/v1/refunds/{seg(id)}/void", idempotency_key=idempotency_key
+            )
+        )

fqris/resources/sandbox.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._object import FQrisObject
+from ._base import Resource, need, seg
+
+
+class Sandbox(Resource):
+    def simulate_payment(
+        self, id: str, *, idempotency_key: str | None = None, **params: Any
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/sandbox/payments/{seg(id)}/simulate",
+                params,
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def simulate_notification(
+        self, *, idempotency_key: str | None = None, **params: Any
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                "/v1/sandbox/devices/simulate-notification",
+                params,
+                idempotency_key=idempotency_key,
+            )
+        )

fqris/resources/webhook_endpoints.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._object import FQrisObject
+from ._base import Resource, need, seg
+
+
+class WebhookEndpoints(Resource):
+    def create(
+        self,
+        *,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+        **params: Any,
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                "/v1/webhook-endpoints",
+                params,
+                idempotency_key=idempotency_key,
+                request_id=request_id,
+            )
+        )
+
+    def retrieve(self, id: str) -> FQrisObject:
+        return need(self._http.request("GET", f"/v1/webhook-endpoints/{seg(id)}"))
+
+    def update(self, id: str, **params: Any) -> FQrisObject:
+        return need(
+            self._http.request("PATCH", f"/v1/webhook-endpoints/{seg(id)}", params)
+        )
+
+    def delete(self, id: str) -> FQrisObject | None:
+        return self._http.request("DELETE", f"/v1/webhook-endpoints/{seg(id)}")
+
+    def list(self) -> FQrisObject:
+        return need(self._http.request("GET", "/v1/webhook-endpoints"))
+
+    def rotate_secret(
+        self, id: str, *, idempotency_key: str | None = None
+    ) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/webhook-endpoints/{seg(id)}/rotate-secret",
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def test(self, id: str, *, idempotency_key: str | None = None) -> FQrisObject:
+        return need(
+            self._http.request(
+                "POST",
+                f"/v1/webhook-endpoints/{seg(id)}/test",
+                idempotency_key=idempotency_key,
+            )
+        )

fqris-0.1.0.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: fqris
+Version: 0.1.0
+Summary: SDK Python resmi untuk FQris REST API v1 (payment gateway QRIS).
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# fqris (Python)
+
+SDK Python resmi untuk [FQris](https://fqris.id) (QRIS payment gateway). Nol dependensi runtime, Python >= 3.9, type hint lengkap (`py.typed`).
+
+Dokumentasi API lengkap: https://fqris.id/docs.
+
+## Instalasi
+
+```bash
+pip install fqris
+```
+
+## Mulai cepat
+
+```python
+import os
+import fqris
+
+client = fqris.Client(os.environ["FQRIS_KEY"])
+
+payment = client.payments.create(
+    amount=20000,
+    reference_id="TOPUP-88812",
+)
+print(payment.checkout_url)
+```
+
+Kunci API harus diawali `fq_live_` atau `fq_test_`. Simpan hanya di backend, jangan di aplikasi Android atau browser.
+
+Respons berupa `FQrisObject`, sebuah `dict` yang juga bisa dibaca lewat atribut: `payment.checkout_url`, `event.data.object.id`, `p.metadata["user_id"]`. Kunci yang bentrok dengan metode `dict` (mis. `items` pada invoice) dibaca lewat `invoice["items"]`, bukan `invoice.items`.
+
+### Opsi
+
+```python
+client = fqris.Client(
+    key,
+    base_url="https://api.fqris.id",  # bawaan
+    max_retries=2,  # bawaan
+    timeout=30.0,  # detik, bawaan
+    http_client=custom_http_client,  # opsional, lihat "Transport kustom"
+)
+```
+
+Body request dikirim sebagai keyword argument. Opsi per request (`idempotency_key`, `request_id`) bersifat keyword-only dan tidak ikut body.
+
+## Retry dan idempotensi
+
+SDK mengulang request yang gagal karena jaringan, timeout, `429`, atau `5xx` (sampai `max_retries` kali, dengan backoff; `Retry-After` dihormati sampai 60 detik).
+
+Setiap POST membawa header `Idempotency-Key`. Kunci dibuat sekali sebelum percobaan pertama dan **sama di semua retry**, jadi payment tidak pernah terbuat dua kali. Untuk operasi yang kamu ulang sendiri (misalnya setelah proses backend mati), berikan kunci yang stabil:
+
+```python
+client.payments.create(
+    amount=20000,
+    reference_id="TOPUP-88812",
+    idempotency_key="TOPUP-88812",
+)
+```
+
+Kunci yang sama dengan isi berbeda ditolak `409 IDEMPOTENCY_KEY_REUSED`, jadi jangan memakai ulang kunci untuk body baru.
+
+## Error
+
+Respons non-2xx (setelah retry habis) menjadi `FQrisError`:
+
+```python
+from fqris import FQrisError
+
+try:
+    client.payments.retrieve("pay_tidak_ada")
+except FQrisError as e:
+    print(e.status, e.code, e, e.request_id)  # sertakan request_id saat menghubungi dukungan
+```
+
+Kolom yang tersedia: `status`, `type`, `code`, `param`, `request_id`, `doc_url`, `headers` (pesan = `str(e)`). Kegagalan jaringan memakai `status` 0 dan `code` `NETWORK_ERROR` atau `TIMEOUT`. ID resource kosong, `.` atau `..` melempar `ValueError` sebelum request dikirim.
+
+## Paginasi
+
+List mengembalikan `{ data, has_more, next_cursor }` dan menerima `limit` (maks 100), `starting_after`, `ending_before`, serta filter seperti `status` dan `created[gte]` (string ISO 8601, kirim lewat `**{"created[gte]": "..."}`).
+
+```python
+page = client.payments.list(
+    limit=20,
+    status="paid",
+    **{"created[gte]": "2026-10-01T00:00:00Z"},
+)
+
+# Atau iterasi semua, halaman berikutnya diambil otomatis:
+for payment in client.payments.list_all(limit=100):
+    print(payment.id)
+```
+
+`list_all` tersedia di `payments`, `customers`, `payment_links`, `invoices`, dan `events`.
+
+## Webhook
+
+Verifikasi **raw body** sebelum di-parse. Flask: `request.get_data()`; Django: `request.body`. Jangan pakai `request.json` atau `json.loads(...)`:
+
+```python
+from fqris import PaymentNotPaidError, SignatureVerificationError, Webhook
+
+@app.post("/webhooks/fqris")
+def fqris_webhook():
+    try:
+        # header FQris-Signature, toleransi bawaan 300 detik
+        event = Webhook.construct_event(
+            request.get_data(),
+            request.headers.get("FQris-Signature"),
+            os.environ["WHSEC"],
+        )
+    except SignatureVerificationError:
+        return "", 400
+    if event.type != "payment.paid":
+        return "", 200
+    if already_processed(event.id):  # event bisa datang lebih dari sekali
+        return "", 200
+
+    # Ambil ulang status sebelum mengkredit. Hanya status `paid` yang lolos.
+    try:
+        payment = client.payments.retrieve_and_assert_paid(event.data.object.id)
+    except PaymentNotPaidError:
+        return "", 200  # mis. sudah refunded: jangan dikredit, jangan di-retry
+    # gangguan jaringan/5xx (FQrisError): biarkan 500 supaya FQris mengirim ulang
+
+    # Cocokkan dengan order sebelum mengkredit.
+    order = find_order((payment.get("metadata") or {}).get("order_id"))
+    if order is None or order.amount != payment.base_amount:
+        alarm_unmatched(payment)  # uang sudah masuk: WAJIB ditindaklanjuti manual
+        mark_processed(event.id)
+        return "", 200
+
+    credit_coins_once(order, payment)  # satu transaksi DB, lihat aturan di bawah
+    mark_processed(event.id)
+    return "", 200
+```
+
+- `Webhook.construct_event(payload, sig_header, secret, tolerance=300)` menerima `str` atau `bytes`. Dict hasil parse melempar `SignatureVerificationError` dengan petunjuk memakai raw body. Header `None` (tidak ada) juga `SignatureVerificationError`.
+- Saat rotasi secret, header memuat dua `v1`; cocok dengan salah satunya sudah cukup.
+- `retrieve_and_assert_paid(id)` melempar `PaymentNotPaidError` (membawa `error.payment`) untuk status selain `paid`, termasuk `refunded` dan `partially_refunded`, sehingga payment yang sudah direfund tidak dikredit. Tangkap error ini dan balas 200; kalau dibiarkan lolos, handler membalas 500 dan FQris mengirim ulang event yang sama terus-menerus.
+- Balas 2xx dalam 10 detik dan kerjakan pekerjaan berat setelahnya. Event bisa datang lebih dari sekali dan tidak berurutan: simpan `event.id` yang sudah selesai diproses dan balas 200 untuk duplikat, serta beri kunci unik per `payment_id` dan per order pada kredit.
+- Jangan mengkredit dari `return_url`: parameternya bisa dipalsukan.
+- **Order tidak ditemukan atau nominal (`base_amount`) tidak cocok: cabang ini WAJIB diberi alarm atau tiket rekonsiliasi**, karena uang sudah masuk. Balas 200 (retry tidak membantu), tetapi jangan diam. Contoh top-up menyediakan callback `on_unmatched(payment, reason)` untuk ini (bawaan cetak ke stderr; ganti dengan alarm sungguhan).
+
+### Satu order, satu kredit
+
+Beri kunci unik per `payment_id` **dan** per order di DB, di dalam satu transaksi. Satu `reference_id` hanya untuk satu payment (`409 DUPLICATE_REFERENCE`), jadi untuk mencoba lagi kamu membuat payment baru dengan `reference_id` baru. Payment lama dan baru bisa sama-sama lunas: kredit yang pertama, lalu `refunds.create` untuk yang kedua. Membatalkan payment lama tidak cukup, karena payment `cancelled` masih bisa menjadi `paid` selama masa tenggang.
+
+### paid_late dan paid_after_cancel
+
+- `paid_late: true`: pembeli membayar setelah `expires_at`, dalam masa tenggang (bawaan 30 menit).
+- `paid_after_cancel: true`: kamu membatalkan payment, tetapi pembeli membayar QR-nya dalam masa tenggang.
+
+Keduanya datang sebagai `payment.paid` dan lolos `retrieve_and_assert_paid` karena statusnya `paid`. Ordermu mungkin sudah kamu tandai gagal: kredit atau refund sesuai kebijakanmu. Tandai order gagal hanya setelah masa tenggang habis.
+
+## Sandbox
+
+Pakai kunci `fq_test_`. Data test terpisah total dari live.
+
+```python
+client = fqris.Client(os.environ["FQRIS_TEST_KEY"])
+payment = client.payments.create(amount=20000, reference_id="TEST-1")
+
+client.sandbox.simulate_payment(payment.id, result="paid")  # atau "expired" | "paid_late"
+```
+
+## Refund
+
+```python
+client.refunds.create(
+    "pay_01JA2Z3K8M",
+    amount=20137,
+    reason="customer_request",
+    note="Koin gagal masuk",
+)
+```
+
+## Transport kustom
+
+Bawaannya `urllib` dari standard library. Untuk proxy, tes, atau library HTTP lain, berikan objek dengan metode `send(method, url, headers, body, timeout) -> HttpResponse` lewat `http_client=`. Respons non-2xx dikembalikan sebagai `HttpResponse` (bukan exception); kegagalan jaringan dilempar sebagai `TransportError`.
+
+```python
+from fqris import HttpResponse, TransportError
+
+class MyHttp:
+    def send(self, method, url, headers, body, timeout) -> HttpResponse: ...
+
+client = fqris.Client(key, http_client=MyHttp())
+```
+
+## Resource lain
+
+`payments` (`create`, `retrieve`, `list`, `list_all`, `cancel`, `events`, `qr`, `retrieve_and_assert_paid`), `refunds`, `sandbox`, `customers`, `payment_links`, `invoices` (termasuk `finalize`, `void`, `send`, `pdf`), `webhook_endpoints` (termasuk `rotate_secret`, `test`), dan `events` (termasuk `resend`). Nama metode sama dengan SDK Node dalam snake_case; `del` menjadi `delete`.
+
+`GET /v1/events/stream` (SSE) belum dibungkus SDK ini; panggil langsung dengan header `Authorization: Bearer <key>` bila perlu.
+
+## Contoh: top-up koin
+
+[`examples/topup.py`](./examples/topup.py) di repositori memuat alur lengkap sesuai panduan "Top-up koin": backend membuat payment (`reference_id` `TOPUP-<order>`, `metadata` berisi `user_id`), menerima webhook dengan raw body, mengambil ulang lewat `retrieve_and_assert_paid`, mencocokkan order dan nominal (tidak cocok -> `on_unmatched`), mengabaikan `event.id` ganda, mengkredit koin sekali per order, dan me-refund payment kedua yang lunas untuk order yang sama.
+
+Ringkasnya:
+
+```python
+topup = Topup(fqris.Client(os.environ["FQRIS_KEY"]), store, os.environ["WHSEC"])
+
+# Aplikasi Android -> backend-mu: buat payment, buka checkout_url di Custom Tab.
+@app.post("/topup")
+def start():
+    return topup.start(current_user.id, "koin-200")
+
+# FQris -> backend-mu.
+@app.post("/webhooks/fqris")
+def webhook():
+    code = topup.handle_webhook(request.get_data(), request.headers.get("FQris-Signature"))
+    return "", code
+```
+
+## Lisensi
+
+MIT

fqris-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+fqris/__init__.py,sha256=sSYGs7ORBSD4YIVae3MEzGtExR-NuaazNpwV38sCK_Q,500
+fqris/_client.py,sha256=EpP2Z3TJKuEy5dEBTDWGvHk7zhwFiZJCuiNrrfzVPG0,1606
+fqris/_errors.py,sha256=XZB2hdIuiR4B0JRNbHlmSmm0TPUtE9mREbWwJV4aPBg,1266
+fqris/_http.py,sha256=NI_t54OEDUqwSoDWaU9HnFESMA4AhdZdB92evyCzItw,6842
+fqris/_object.py,sha256=rgsVi_kH73IdaM1v6wKzVe7O4oRVfgxYFvYIjLseoVQ,972
+fqris/_pagination.py,sha256=Ag5gOMuR-ylOzhD56eXhIOKia-ZYeXH_KvrVCVQMKW4,655
+fqris/_transport.py,sha256=eGQFP4EyVzytYDm-gwz_NCJ-ByiLXFXcb6Pxn5OF0aQ,2609
+fqris/_webhook.py,sha256=wYXuHu0WWgVseaEkBg_EAxeuMgsfvS3XArp7VFiUFr8,3083
+fqris/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fqris/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fqris/resources/_base.py,sha256=d5_3vP8GOciiz0-rezmtjMQa_luj8EcGfbDpXsdORIE,727
+fqris/resources/customers.py,sha256=P9s24t8z_V_9lSGpZwgCYgH1a2L_TklxJHVADxXEufg,1226
+fqris/resources/events.py,sha256=NZt7QjkOAH3NIljY7Xj6mcMyMM544uNnYJha8xntnEc,1024
+fqris/resources/invoices.py,sha256=_5xKNXwK9pPcTOQf0WnWYCizxPqdlF6u4HsYf2A9rC8,2380
+fqris/resources/payment_links.py,sha256=D6f6o2uxlD5yUbk6LmZq40pkJLAvcwi8sZY49gCidnM,1538
+fqris/resources/payments.py,sha256=Wpsr6Ur3B3md-VbzLstAcrEcIYn6qQ9hc9W3IJ8kb9Y,2227
+fqris/resources/refunds.py,sha256=0xbB_OT2fzLO-Rj_Eg0_G6bqWYovSsLsGwe0Hy4klSA,961
+fqris/resources/sandbox.py,sha256=zUGkaZDQyrGMtGzHngm8d_7HZFOliNGyhIhPztPoRcQ,874
+fqris/resources/webhook_endpoints.py,sha256=xhYnGlpMcrGw4Y-5UWpSY90PPCBPqcWlpdkSipMO7DU,1757
+fqris-0.1.0.dist-info/METADATA,sha256=mfS1ULOF3YiYNNlTop-2YTAGPGHIhTA_p3o9qJsASj0,9823
+fqris-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+fqris-0.1.0.dist-info/licenses/LICENSE,sha256=WGxDAlAg88teidT71I2vRHQSdcbxsWYlVivAseIwpfY,1062
+fqris-0.1.0.dist-info/RECORD,,

fqris-0.1.0.dist-info/WHEEL

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

fqris-0.1.0.dist-info/licenses/LICENSE

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