Metadata-Version: 2.4
Name: QrisMerchantID
Version: 0.2.0
Summary: Unofficial Indonesian QRIS merchant API client for Python — GoPay/GoBiz + ShopeePay (manual-token feed)
Author: AlfinAI
License: MIT
Project-URL: Homepage, https://github.com/AlfinAI/QrisMerchantID
Project-URL: Repository, https://github.com/AlfinAI/QrisMerchantID
Project-URL: Issues, https://github.com/AlfinAI/QrisMerchantID/issues
Project-URL: Changelog, https://github.com/AlfinAI/QrisMerchantID/blob/main/CHANGELOG.md
Project-URL: Reference-GoBiz, https://github.com/kavionn/gobiz-payment
Project-URL: Reference-ShopeePay, https://github.com/alhifnywahid/merchantid
Keywords: qris,gopay,gobiz,shopeepay,merchant,payment,indonesia,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=6; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="QrisMerchantID logo" width="140" />
</p>

# QrisMerchantID — Unofficial Indonesian QRIS merchant API client for Python

[![Tests](https://github.com/AlfinAI/QrisMerchantID/actions/workflows/test.yml/badge.svg)](https://github.com/AlfinAI/QrisMerchantID/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/QrisMerchantID.svg)](https://pypi.org/project/QrisMerchantID/)
[![Python](https://img.shields.io/pypi/pyversions/QrisMerchantID.svg)](https://pypi.org/project/QrisMerchantID/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Telegram](https://img.shields.io/badge/Telegram-@JoestarMojo-26A5E4?logo=telegram)](https://t.me/JoestarMojo)
[![Discussions](https://img.shields.io/github/discussions/AlfinAI/QrisMerchantID?label=discussions)](https://github.com/AlfinAI/QrisMerchantID/discussions)

One Python package for Indonesia's QRIS merchant APIs — read your own merchant
data with typed, tested, offline-friendly code:

- 🧾 **GoPay / GoBiz** — OTP + password login, merchants, transactions, payouts,
  dynamic QRIS, payment watcher.
- 🛍️ **ShopeePay** — OTP login (or manual `B:` token), stores, normalized feed,
  payment watcher.
- 🔬 **Researched, not guessed** — every endpoint traced to a capture or a
  reference repo; unknowns are marked TODO, never shipped as fact.

Each merchant has its own guide with the full tutorial and flow diagrams:

| Provider | Guide | Status |
|---|---|---|
| GoPay / GoBiz merchant | [docs/gopay/](docs/gopay/) | ✅ auth, users, merchants, transactions, payouts, QRIS, watcher |
| ShopeePay partner | [docs/shopee/](docs/shopee/) | ✅ OTP login, stores, transactions, watcher (login or manual `B:` token) |

> Research/educational use only. Not affiliated with GoTo/GoPay/GoBiz or
> Shopee/Sea Group. Read-only by design in v0.2.0 — it only *reads* your own
> merchant data (login + history + payouts) and never moves money.

## ⚠️ Disclaimer — harap dibaca dulu

**English.** This is an **unofficial, independent research project**. It is NOT
affiliated with, endorsed by, or supported by GoTo, GoPay, GoBiz, Shopee, Sea
Group, or any reference-repo author. It is provided for **research and
educational purposes only**, without warranty of any kind. Using unofficial
APIs may violate the providers' Terms of Service and can lead to rate limits,
suspension, or termination of your accounts. **You use this software entirely
at your own risk — the author (AlfinAI) shall not be liable for any loss,
damage, account action, or legal consequence arising from its use.** Credentials
and tokens you enter stay on your machine (they are only ever sent to the
providers' own official servers) — never commit `.env`, `*.har`, or token/OTP
cache files to any repository.

**Bahasa Indonesia.** Ini adalah **proyek riset independen yang tidak resmi
(unofficial)**. TIDAK berafiliasi, didukung, atau disetujui oleh GoTo, GoPay,
GoBiz, Shopee, Sea Group, maupun author repo referensi mana pun. Disediakan
**hanya untuk riset dan edukasi**, tanpa jaminan apa pun. Penggunaan API tidak
resmi dapat melanggar Syarat & Ketentuan penyedia dan berakibat akun dibatasi,
ditangguhkan, atau dihapus. **Segala risiko dan akibat yang timbul sepenuhnya
menjadi tanggung jawab pengguna — author (AlfinAI) tidak bertanggung jawab atas
kerugian, kerusakan, tindakan terhadap akun, atau konsekuensi hukum apa pun dari
penggunaan software ini.** Kredensial/token hanya tersimpan di mesin Anda (dan
hanya dikirim ke server resmi penyedia) — jangan pernah commit file `.env`,
`*.har`, atau cache token/OTP ke repo mana pun.

## Contents

- [Installation](#installation)
- [Core concepts](#core-concepts) (money · sessions · errors)
- [Quickstart](#quickstart)
- [Provider guides](#provider-guides)
- [Roadmap](#roadmap)
- [Development](#development) · [Research](#research) · [Credits](#credits) ·
  [Contributing](#contributing) · [Contact](#contact)

## Installation

```bash
pip install QrisMerchantID
```

Requires Python 3.10+ and one dependency: [`httpx`](https://www.python-httpx.org/).

## Core concepts

Three things to understand before anything else:

1. **Money differs per provider — never mix them.** GoPay answers minor units
   (sen): `gross_amount: 10600000` = Rp106.000, convert with
   `gopay.money.to_rupiah()`. ShopeePay answers whole rupiah as grouped
   strings: `"409.662"` = Rp409.662, parse with
   `shopee.money.parse_id_amount()`. Never guess.
2. **Sessions are yours to keep.** GoPay: cache the `access_token`, revalidate
   cheaply (`merchants.search()`); on HTTP 401, log in again. ShopeePay: log
   in with OTP and `refresh_session()` without re-OTP, or paste a manual `B:`
   token; on codes `200020`/`2010000`, renew it.
3. **Every HTTP error raises `ApiException`.** It carries `.http_status`,
   `.code` (when the provider sent one), `.payload` (full body), and a readable
   message. Transport errors (DNS/connect/timeout) retry with backoff; HTTP
   errors never retry.

## Quickstart

```python
from qrismerchantid import GoPayMerchant, ShopeePayPartner

# --- GoPay: OTP login, then read your history ---
gopay = GoPayMerchant()
otp = gopay.auth.request_otp("0812xxxxxxx")
session = gopay.auth.login_with_otp(input("OTP: "), otp["otp_token"])
txns = gopay.transactions.analytics("G...", days=7)
print(txns["total"], "transactions")

# --- ShopeePay: token (or sp.auth OTP login), then watch a store ---
sp = ShopeePayPartner(token="B:...")   # token how-to: docs/shopee/token.md
print(sp.stores.list_stores())
watcher = sp.watch(7)
watcher.seed()
paid = watcher.wait_for_payment(409662, timeout=300)  # Rp409.662
print("PAID:", paid["id"])
```

## Provider guides

- **[GoPay / GoBiz merchant →](docs/gopay/)** — login (OTP + password),
  session cache, users, merchants, transactions, payouts, dynamic QRIS, payment
  watcher, configuration, and the login/payment flow diagrams.
- **[ShopeePay partner →](docs/shopee/)** — OTP login + session renewal,
  manual-token setup, stores, normalized transaction feed, whole-rupiah money
  rules, payment watcher, configuration, and the payment flow diagram.

## Roadmap

- [x] GoPay provider — auth, merchants, transactions, payouts, QRIS, watcher.
- [x] ShopeePay provider — OTP login, stores, feed, watcher.
- [ ] Live verification against real partner accounts (TODO-S1) — field
      reports welcome in [Discussions](https://github.com/AlfinAI/QrisMerchantID/discussions).
- [ ] `v0.2.0` PyPI release.
- [ ] Your idea here — open a Discussion or a feature request.

## Development

```bash
pip install -e ".[dev]"
pytest          # 100% offline — never hits the real API
ruff check src tests && ruff format --check src tests
mypy src        # strict
python -m build
```

Runnable flows (need real merchant credentials via env, except QRIS):
`examples/` — `01_login_otp.py`, `02_merchants.py`, `03_transactions.py`,
`04_qris_dynamic.py`, `05_watch_payment.py`, `06_shopee_stores.py`,
`07_shopee_transactions.py`, `08_shopee_watch.py`, `09_shopee_login_otp.py`.

## Research

Full endpoint research (repos surveyed + anonymized HAR verification):
`research/RESEARCH_GOPAY_SHOPEEPAY.md` + the ShopeePay deep-dive
`research/ANALYSIS_SHOPEEPAY_PHASE_B.md`. Per-service pages: `docs/gopay/`,
`docs/shopee/`.

## Credits

API knowledge: [kavionn/gobiz-payment](https://github.com/kavionn/gobiz-payment),
[warungerik/API-GOPAY-MERCHANT](https://github.com/warungerik/API-GOPAY-MERCHANT),
[alhifnywahid/merchantid](https://github.com/alhifnywahid/merchantid),
[ahmadzakiyox/gopay-api-gateaway](https://github.com/ahmadzakiyox/gopay-api-gateaway),
[ahmadzakiyox/shoppepay-api-gateway](https://github.com/ahmadzakiyox/shoppepay-api-gateway),
[namtxs/gopay-api](https://github.com/namtxs/gopay-api).
Python package maintained by AlfinAI.

## Contributing

- 🐞 Found a bug? [Open a bug report](https://github.com/AlfinAI/QrisMerchantID/issues/new?template=bug_report.md)
      — offline repro snippets get fixed fastest.
- 💡 Want an endpoint? [Request it](https://github.com/AlfinAI/QrisMerchantID/issues/new?template=feature_request.md)
      with a traffic sample or upstream link as evidence.
- 💬 Questions, ideas, show-and-tell →
      [Discussions](https://github.com/AlfinAI/QrisMerchantID/discussions).
- 🔒 Security issue? See [SECURITY.md](SECURITY.md) — never file it publicly.
- 🤝 Pull requests welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## Contact

Questions, bug reports, or research collaboration — reach me on Telegram:
**[@JoestarMojo](https://t.me/JoestarMojo)**.

## License

MIT — see [LICENSE](LICENSE).
