fqris 0.1.0__tar.gz

fqris-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+uv.lock
+__pycache__/
+*.egg-info/
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

fqris-0.1.0/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.

fqris-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,219 @@
+# 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/examples/topup.py

@@ -0,0 +1,193 @@
+"""Contoh top-up koin (PRD §13.6): backend membuat payment, menerima webhook, lalu mengkredit koin tepat sekali.
+
+Tanpa dependensi framework: `Topup.handle_webhook` menerima raw body dan mengembalikan kode HTTP, jadi
+pasangannya dengan Flask/Django cukup beberapa baris (lihat paling bawah). Di aplikasimu `import fqris`.
+"""
+
+from __future__ import annotations
+
+import sys
+import uuid
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+from fqris import (
+    Client,
+    FQrisObject,
+    PaymentNotPaidError,
+    SignatureVerificationError,
+    Webhook,
+)
+
+PACKAGES = {"koin-200": {"coins": 200, "amount": 20000}}
+
+
+@dataclass
+class Order:
+    id: str
+    user_id: str
+    coins: int
+    amount: int
+    status: str = "awaiting_payment"  # 'awaiting_payment' | 'credited'
+    payment_id: str | None = None
+    # payment yang mengkredit order ini (untuk membedakan event ganda dari payment kedua).
+    credited_by: str | None = None
+
+
+class Store(Protocol):
+    """Ganti dengan tabel DB. `credit_once` harus satu transaksi dengan UNIQUE(order_id) dan UNIQUE(payment_id)."""
+
+    def create_order(self, user_id: str, package_id: str) -> Order: ...
+
+    def attach_payment(self, order_id: str, payment_id: str) -> None: ...
+
+    def get_order(self, order_id: str) -> Order | None: ...
+
+    def credit_once(self, order_id: str, payment_id: str) -> bool:
+        """True bila koin dikredit sekarang, False bila order itu sudah pernah dikredit."""
+        ...
+
+    def is_processed(self, event_id: str) -> bool:
+        """Event sudah selesai diproses? (tabel `processed_events` dengan UNIQUE(event_id))."""
+        ...
+
+    def mark_processed(self, event_id: str) -> None: ...
+
+
+class MemoryStore:
+    def __init__(self) -> None:
+        self.orders: dict[str, Order] = {}
+        self.coins: dict[str, int] = {}
+        self.processed_events: set[str] = set()
+
+    def create_order(self, user_id: str, package_id: str) -> Order:
+        order = Order(id=f"ord_{uuid.uuid4()}", user_id=user_id, **PACKAGES[package_id])  # type: ignore[arg-type]
+        self.orders[order.id] = order
+        return order
+
+    def attach_payment(self, order_id: str, payment_id: str) -> None:
+        order = self.orders.get(order_id)
+        if order:
+            order.payment_id = payment_id
+
+    def get_order(self, order_id: str) -> Order | None:
+        return self.orders.get(order_id)
+
+    def credit_once(self, order_id: str, payment_id: str) -> bool:
+        order = self.orders.get(order_id)
+        if order is None or order.status == "credited":
+            return False
+        order.status = "credited"
+        order.credited_by = payment_id
+        self.coins[order.user_id] = self.coins.get(order.user_id, 0) + order.coins
+        return True
+
+    def is_processed(self, event_id: str) -> bool:
+        return event_id in self.processed_events
+
+    def mark_processed(self, event_id: str) -> None:
+        self.processed_events.add(event_id)
+
+
+def default_on_unmatched(payment: FQrisObject, reason: str) -> None:
+    print(
+        f"[FQris] payment {payment.id} lunas tetapi tidak cocok ({reason}): rekonsiliasi manual",
+        file=sys.stderr,
+    )
+
+
+class Topup:
+    """`on_unmatched(payment, reason)`: reason `order_not_found` | `amount_mismatch`.
+
+    Uang sudah masuk tetapi order tidak ditemukan atau nominalnya beda. WAJIB diberi alarm (Sentry, Slack,
+    tiket rekonsiliasi) dan ditindaklanjuti manual; jangan hanya dicatat. Bawaan: cetak ke stderr.
+    """
+
+    def __init__(
+        self,
+        fqris: Client,
+        store: Store,
+        webhook_secret: str,
+        on_unmatched: Callable[[FQrisObject, str], None] | None = None,
+    ) -> None:
+        self.fqris = fqris
+        self.store = store
+        self.webhook_secret = webhook_secret
+        self.on_unmatched = on_unmatched or default_on_unmatched
+
+    def start(self, user_id: str, package_id: str) -> dict[str, str]:
+        """Dipanggil aplikasi Android lewat backend-mu. Kembalikan `checkout_url` untuk dibuka di Custom Tab."""
+        order = self.store.create_order(user_id, package_id)
+        payment = self.fqris.payments.create(
+            amount=order.amount,
+            reference_id=f"TOPUP-{order.id}",  # unik per payment: untuk mencoba lagi, buat order dan reference_id baru
+            metadata={"user_id": user_id, "order_id": order.id},
+            idempotency_key=f"TOPUP-{order.id}",  # retry setelah timeout tidak membuat payment ganda
+        )
+        self.store.attach_payment(order.id, payment.id)
+        return {"order_id": order.id, "checkout_url": payment.checkout_url}
+
+    def handle_webhook(self, raw_body: bytes | str, sig_header: str | None) -> int:
+        """`raw_body` HARUS body mentah, bukan hasil `request.json`. Mengembalikan kode HTTP."""
+        try:
+            event = Webhook.construct_event(raw_body, sig_header, self.webhook_secret)
+        except SignatureVerificationError:
+            return 400
+        if event.type != "payment.paid":
+            return 200
+        # Event yang sama bisa dikirim ulang (at-least-once): sudah selesai diproses -> balas 200 tanpa kerja apa pun.
+        if self.store.is_processed(event.id):
+            return 200
+
+        # Ambil ulang dari API: hanya status `paid` yang lolos (refunded, dll melempar PaymentNotPaidError).
+        try:
+            payment = self.fqris.payments.retrieve_and_assert_paid(
+                str(event.data.object.id)
+            )
+        except PaymentNotPaidError:
+            return 200
+        # Gangguan jaringan/5xx (FQrisError) dibiarkan lolos: framework membalas 500 supaya FQris mengirim ulang.
+
+        order = self.store.get_order(
+            (payment.get("metadata") or {}).get("order_id", "")
+        )
+        if order is None or payment.base_amount != order.amount:
+            # Uang sudah masuk tetapi tidak bisa dikaitkan ke order: alarm dulu, tetap balas 200 (retry tidak membantu).
+            self.on_unmatched(
+                payment, "order_not_found" if order is None else "amount_mismatch"
+            )
+            self.store.mark_processed(event.id)
+            return 200
+
+        # paid_late dan paid_after_cancel (payment dibatalkan lalu dibayar) diperlakukan sama dengan paid: di sini
+        # dikredit. Kebijakan lain, mis. refund bila ordermu sudah ditandai gagal, ditaruh di cabang ini.
+        if self.store.credit_once(order.id, payment.id):
+            self.store.mark_processed(event.id)
+            return 200
+
+        # Order sudah dikredit dari payment lain (pembeli membayar payment lama dan baru): kembalikan uang yang kedua.
+        credited = self.store.get_order(order.id)
+        if credited is None or credited.credited_by != payment.id:
+            self.fqris.refunds.create(
+                payment.id,
+                amount=payment.final_amount,
+                reason="duplicate",
+                note=f"Order {order.id} sudah dikredit",
+                idempotency_key=f"refund-{payment.id}",
+            )
+        self.store.mark_processed(event.id)
+        return 200
+
+
+# Pasangan dengan Flask:
+#
+#   topup = Topup(fqris.Client(os.environ["FQRIS_KEY"]), store, os.environ["WHSEC"])
+#
+#   @app.post("/topup")
+#   def start():
+#       return topup.start(current_user.id, "koin-200")
+#
+#   @app.post("/webhooks/fqris")
+#   def webhook():
+#       code = topup.handle_webhook(request.get_data(), request.headers.get("FQris-Signature"))
+#       return "", code