bitsopay 0.1.0__tar.gz

bitsopay-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-14
+
+First release, by Bitsophia.
+
+### Added
+- `/ready` readiness probe; `X-Request-ID` propagation; structured request logging (`bitsopay.server` logger).
+- Security headers on every response: `Content-Security-Policy`, HSTS (over HTTPS), `Permissions-Policy`,
+  `Cross-Origin-*`.
+- Admin brute-force throttling (`bitsopay.ratelimit.FailureLimiter`, `429` + `Retry-After`).
+- `BITSOPAY_TRUST_PROXY` and `BITSOPAY_LOG_LEVEL` settings; `HEAD` support.
+- `python -m bitsopay`, `bitsopay --version`; `SQLiteStore` and the server app are context managers (`close()`).
+- Full documentation set, Dockerfile, CI, CodeQL and PyPI Trusted Publishing workflows.
+
+### Changed
+- `server.py` rewritten with strict typing; unhandled errors now return a generic 500 with a request id.
+- A short `BITSOPAY_SECRET` now fails at startup instead of at the first request.
+- Package metadata, `py.typed`, `ruff` and `mypy --strict` configuration.
+
+### Fixed
+- `limit=-1` on the history endpoint returned every row (SQLite treats a negative `LIMIT` as unlimited); paging
+  parameters are now validated (400).
+- Non-integer `expires_in` in the API caused a 500; it is now a 400.
+- SQLite connections opened by the CLI were never closed.
+
+[Unreleased]: https://github.com/Sudharsansm/Bitsopay/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Sudharsansm/Bitsopay/releases/tag/v0.1.0

bitsopay-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,103 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free
+experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy
+community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take
+appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening,
+offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
+issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially
+representing the community in public spaces. Examples of representing our community include using an official email
+address, posting via an official social media account, or acting as an appointed representative at an online or
+offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders
+responsible for enforcement by opening a **private** report through GitHub
+([Security → Report a vulnerability](https://github.com/Sudharsansm/Bitsopay/security/advisories/new), marked as a
+conduct report) or by contacting the maintainer [@Sudharsansm](https://github.com/Sudharsansm) through their GitHub
+profile. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they
+deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the
+community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the
+violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved,
+including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels like social media. Violating these
+terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a
+specified period of time. No public or private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead
+to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate
+behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this code of conduct, see the FAQ at <https://www.contributor-covenant.org/faq>.

bitsopay-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to Bitsopay
+
+Thanks for helping! Bitsopay is a small, security-sensitive library, so we value focused changes with tests.
+By taking part you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Ways to contribute
+
+- **Report a bug** or **request a feature** via [issues](https://github.com/Sudharsansm/Bitsopay/issues) (use the templates).
+- **Security problems**: do not file an issue; follow [SECURITY.md](SECURITY.md).
+- **Improve docs**: typos, clearer examples and deployment notes are always welcome.
+- **Send a pull request**: for anything larger than a small fix, open an issue first so we can agree on the approach.
+
+## Development setup
+
+```bash
+git clone https://github.com/<you>/Bitsopay && cd Bitsopay
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install        # optional: runs ruff on commit (pip install pre-commit)
+```
+
+## Before you open a PR
+
+```bash
+make check      # = ruff check + ruff format --check + mypy --strict + pytest (coverage gate 92%)
+```
+
+- Add or update **tests** for every behavior change; bug fixes need a test that fails without the fix.
+- Keep the package at **one runtime dependency** (`segno`). New dependencies need a strong justification.
+- Keep Python **3.9** compatibility (CI runs 3.9 to 3.13).
+- Public API changes need docstrings, docs updates and a `CHANGELOG.md` entry under **Unreleased**.
+- Never log or return secrets, amounts or UPI IDs on public routes.
+
+## Pull request guidelines
+
+1. Branch from `main`; one logical change per PR.
+2. Write a clear description: what, why, and how you tested.
+3. Use [Conventional Commits](https://www.conventionalcommits.org/) style subjects (`fix:`, `feat:`, `docs:`, `test:`, `chore:`).
+4. CI must be green. A maintainer will review; please respond to feedback and keep the PR up to date.
+
+## Releasing
+
+Maintainers only; see [docs/releasing.md](docs/releasing.md).
+
+## License
+
+Contributions are licensed under the project's [MIT license](LICENSE).

bitsopay-0.1.0/LICENSE

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

bitsopay-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE README.md CHANGELOG.md SECURITY.md CODE_OF_CONDUCT.md CONTRIBUTING.md
+recursive-include src/bitsopay py.typed
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include deploy *
+include tests/*.py
+prune assets
+global-exclude __pycache__ *.py[cod] .DS_Store

bitsopay-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: bitsopay
+Version: 0.1.0
+Summary: Dynamic UPI QR codes and tamper-proof payment links from a UPI ID and amount. Zero-gateway, merchant-verified payments.
+Author: Bitsophia
+Maintainer: Bitsophia
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sudharsansm/Bitsopay
+Project-URL: Documentation, https://github.com/Sudharsansm/Bitsopay/tree/main/docs
+Project-URL: Repository, https://github.com/Sudharsansm/Bitsopay
+Project-URL: Issues, https://github.com/Sudharsansm/Bitsopay/issues
+Project-URL: Changelog, https://github.com/Sudharsansm/Bitsopay/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/Sudharsansm/Bitsopay/security/policy
+Keywords: upi,qr,qr-code,payments,india,payment-link,bhim,gpay,phonepe,paytm,fintech,wsgi,bitsophia
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: segno<2,>=1.6
+Provides-Extra: server
+Requires-Dist: gunicorn>=22; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff==0.15.22; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sudharsansm/Bitsopay/main/assets/bitsopay-logo.png" alt="Bitsopay" width="420">
+</p>
+
+<p align="center"><b>Dynamic UPI QR codes and tamper-proof payment links, with no payment gateway.</b></p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bitsopay/"><img alt="PyPI" src="https://img.shields.io/pypi/v/bitsopay?label=PyPI&color=blue"></a>
+  <a href="https://github.com/Sudharsansm/Bitsopay/blob/main/pyproject.toml"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg"></a>
+  <a href="https://github.com/Sudharsansm/Bitsopay/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Sudharsansm/Bitsopay/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href="https://docs.astral.sh/ruff/"><img alt="Ruff" src="https://img.shields.io/badge/lint-ruff-261230.svg"></a>
+  <img alt="Typed" src="https://img.shields.io/badge/typing-strict-2a6db2.svg">
+</p>
+
+<p align="center">
+  <a href="README.md">README</a> ·
+  <a href="CODE_OF_CONDUCT.md">Code of conduct</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a> ·
+  <a href="LICENSE">MIT license</a> ·
+  <a href="SECURITY.md">Security</a>
+</p>
+
+---
+
+## About
+
+**Bitsopay** turns a UPI ID and an amount into a QR code or a shareable payment link. The customer scans
+it with any UPI app (GPay, PhonePe, Paytm, BHIM, and others) and the amount is already filled in. Money goes
+straight to *your* UPI ID.
+
+It is a framework developed by **[Bitsophia](https://github.com/Sudharsansm)**, in the same family as
+[Bitscrape](https://github.com/Sudharsansm/Bitscrape).
+
+> **Bitsopay is not a payment gateway.** It never sees or moves money, and it cannot detect that a customer
+> has paid. You confirm the payment in your bank or UPI app, then record it with `mark_paid`. In exchange there are
+> no API keys, no gateway fees and no KYC with a third party.
+
+## Features
+
+- **QR from UPI ID + amount**: PNG, SVG or base64 data URI, with validated UPI IDs, `Decimal` amounts, notes and references.
+- **Three kinds of payment link**:
+  - *Short links with history*: the URL holds only a reference; UPI ID and amount stay on your server (SQLite or your own store).
+  - *Database-free short links*: amount and expiry are encrypted and signed inside the URL.
+  - *Signed links*: HMAC-SHA256 with expiry, for existing sites.
+- **Payment page**: mobile-friendly, QR, UPI app buttons, live countdown, no external requests.
+- **Production WSGI server**: merchant API, `/health` and `/ready` probes, security headers (CSP, HSTS), request IDs,
+  structured logging, admin brute-force throttling.
+- **CLI** for scripting and operations.
+- **One dependency** ([`segno`](https://pypi.org/project/segno/), pure Python). Python 3.11+. Fully typed (`mypy --strict`).
+
+## Install
+
+```bash
+pip install bitsopay            # library + CLI
+pip install "bitsopay[server]"  # plus gunicorn for production serving
+```
+
+## Quick start
+
+### 1. A QR code
+
+```python
+from bitsopay import UPIPayment, new_reference, save_qr, qr_data_uri
+
+pay = UPIPayment(
+    upi_id="shop@okhdfcbank",
+    payee_name="My Shop",
+    amount=499,                 # None lets the customer type the amount
+    note="Order 1042",
+    reference=new_reference(),  # use it to match the payment when you verify
+)
+pay.uri                         # upi://pay?pa=shop@okhdfcbank&pn=My%20Shop&am=499.00&cu=INR&...
+save_qr(pay, "order-1042.png")  # or .svg
+html_src = qr_data_uri(pay)     # <img src="...">
+```
+
+### 2. Short links with payment history
+
+```python
+from bitsopay import PaymentLinks, SQLiteStore
+
+with SQLiteStore("payments.db") as store:
+    links = PaymentLinks(store, "https://pay.example.com")
+    link = links.create("shop@okhdfcbank", "My Shop", 499, note="Order 1042", expires_in=3600)
+    print(link.url)             # https://pay.example.com/p/BP684BF1555E4B4907  -> send to the customer
+    link.save("link-qr.png")
+
+    # after YOU confirmed the money in your bank / UPI app:
+    links.mark_paid(link.reference, note="UTR 4123...")
+    links.history(status="pending", limit=20)   # paid | pending | cancelled | expired
+```
+
+### 3. Database-free links
+
+```python
+from bitsopay import StatelessLinks
+
+links = StatelessLinks("shop@okhdfcbank", "My Shop", secret=SECRET, base_url="https://pay.example.com")
+link = links.create(499, expires_in=3600)
+link.url
+```
+
+More in [docs/usage.md](docs/usage.md) and [`examples/`](examples).
+
+## Run the server
+
+```bash
+pip install "bitsopay[server]"
+export BITSOPAY_DB=/var/lib/bitsopay/payments.db
+export BITSOPAY_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+export BITSOPAY_BASE_URL=https://pay.example.com
+gunicorn -c deploy/gunicorn.conf.py "bitsopay.server:create_app()"
+```
+
+Or with Docker: `docker compose up -d` (see [docs/deployment.md](docs/deployment.md)).
+
+```bash
+curl -X POST https://pay.example.com/api/payments \
+  -H "Authorization: Bearer $BITSOPAY_ADMIN_TOKEN" \
+  -d '{"upi_id":"shop@okhdfcbank","payee_name":"My Shop","amount":499,"expires_in":3600}'
+```
+
+| Route | Purpose |
+|---|---|
+| `GET /p/<ref>` | Customer payment page |
+| `GET /p/<ref>/qr.png` · `qr.svg` | QR image |
+| `GET /p/<ref>/status` | Status only (no amount or UPI ID) |
+| `POST /api/payments` | Create a link *(admin)* |
+| `GET /api/payments?status=&limit=&offset=` | History *(admin)* |
+| `GET /api/payments/<ref>` | One record *(admin)* |
+| `POST /api/payments/<ref>/paid` · `/cancel` | Change status *(admin)* |
+| `GET /health` · `/ready` | Liveness and readiness probes |
+
+Full reference: [docs/api.md](docs/api.md).
+
+## Command line
+
+```bash
+bitsopay qr --upi-id shop@okhdfcbank --name "My Shop" --amount 499 -o pay.png
+bitsopay create-link --db payments.db --base-url https://pay.example.com \
+  --upi-id shop@okhdfcbank --name "My Shop" --amount 499 --expires-in 3600
+bitsopay history --db payments.db --status pending
+bitsopay mark-paid BP684BF1555E4B4907 --db payments.db --note "UTR 4123..."
+```
+
+Run `bitsopay --help` for all commands. [docs/cli.md](docs/cli.md) has the details.
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `BITSOPAY_DB` | SQLite path; enables short links, history and the full merchant API |
+| `BITSOPAY_SECRET` | 16+ char secret for signed and database-free links |
+| `BITSOPAY_UPI_ID`, `BITSOPAY_PAYEE_NAME` | Merchant identity for database-free links |
+| `BITSOPAY_ADMIN_TOKEN` | 16+ char bearer token for `/api/*` (API is off without it) |
+| `BITSOPAY_BASE_URL` | Public root URL used in returned links |
+| `BITSOPAY_TRUST_PROXY` | `1` to trust `X-Forwarded-For/Proto` (only behind your own proxy) |
+| `BITSOPAY_LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, ... |
+
+## Security
+
+Links cannot be edited or guessed, secrets are compared in constant time, the page makes no third-party
+requests, and the admin API is throttled against brute force. Read the [threat model](docs/security-model.md)
+before going live, and report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [Usage guide](docs/usage.md) | Library walkthrough |
+| [API reference](docs/api.md) | HTTP routes, errors and status codes |
+| [CLI](docs/cli.md) | Every command |
+| [Architecture](docs/architecture.md) | How the pieces fit |
+| [Deployment](docs/deployment.md) | gunicorn, nginx, Docker, systemd |
+| [Security model](docs/security-model.md) | Threats and limits |
+| [Releasing](docs/releasing.md) | Publishing to PyPI |
+| [Changelog](CHANGELOG.md) | Version history |
+
+## Development
+
+```bash
+git clone https://github.com/Sudharsansm/Bitsopay && cd Bitsopay
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+make check        # ruff, mypy --strict, pytest with coverage
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Bitsophia

bitsopay-0.1.0/README.md

@@ -0,0 +1,193 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sudharsansm/Bitsopay/main/assets/bitsopay-logo.png" alt="Bitsopay" width="420">
+</p>
+
+<p align="center"><b>Dynamic UPI QR codes and tamper-proof payment links, with no payment gateway.</b></p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bitsopay/"><img alt="PyPI" src="https://img.shields.io/pypi/v/bitsopay?label=PyPI&color=blue"></a>
+  <a href="https://github.com/Sudharsansm/Bitsopay/blob/main/pyproject.toml"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg"></a>
+  <a href="https://github.com/Sudharsansm/Bitsopay/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Sudharsansm/Bitsopay/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href="https://docs.astral.sh/ruff/"><img alt="Ruff" src="https://img.shields.io/badge/lint-ruff-261230.svg"></a>
+  <img alt="Typed" src="https://img.shields.io/badge/typing-strict-2a6db2.svg">
+</p>
+
+<p align="center">
+  <a href="README.md">README</a> ·
+  <a href="CODE_OF_CONDUCT.md">Code of conduct</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a> ·
+  <a href="LICENSE">MIT license</a> ·
+  <a href="SECURITY.md">Security</a>
+</p>
+
+---
+
+## About
+
+**Bitsopay** turns a UPI ID and an amount into a QR code or a shareable payment link. The customer scans
+it with any UPI app (GPay, PhonePe, Paytm, BHIM, and others) and the amount is already filled in. Money goes
+straight to *your* UPI ID.
+
+It is a framework developed by **[Bitsophia](https://github.com/Sudharsansm)**, in the same family as
+[Bitscrape](https://github.com/Sudharsansm/Bitscrape).
+
+> **Bitsopay is not a payment gateway.** It never sees or moves money, and it cannot detect that a customer
+> has paid. You confirm the payment in your bank or UPI app, then record it with `mark_paid`. In exchange there are
+> no API keys, no gateway fees and no KYC with a third party.
+
+## Features
+
+- **QR from UPI ID + amount**: PNG, SVG or base64 data URI, with validated UPI IDs, `Decimal` amounts, notes and references.
+- **Three kinds of payment link**:
+  - *Short links with history*: the URL holds only a reference; UPI ID and amount stay on your server (SQLite or your own store).
+  - *Database-free short links*: amount and expiry are encrypted and signed inside the URL.
+  - *Signed links*: HMAC-SHA256 with expiry, for existing sites.
+- **Payment page**: mobile-friendly, QR, UPI app buttons, live countdown, no external requests.
+- **Production WSGI server**: merchant API, `/health` and `/ready` probes, security headers (CSP, HSTS), request IDs,
+  structured logging, admin brute-force throttling.
+- **CLI** for scripting and operations.
+- **One dependency** ([`segno`](https://pypi.org/project/segno/), pure Python). Python 3.11+. Fully typed (`mypy --strict`).
+
+## Install
+
+```bash
+pip install bitsopay            # library + CLI
+pip install "bitsopay[server]"  # plus gunicorn for production serving
+```
+
+## Quick start
+
+### 1. A QR code
+
+```python
+from bitsopay import UPIPayment, new_reference, save_qr, qr_data_uri
+
+pay = UPIPayment(
+    upi_id="shop@okhdfcbank",
+    payee_name="My Shop",
+    amount=499,                 # None lets the customer type the amount
+    note="Order 1042",
+    reference=new_reference(),  # use it to match the payment when you verify
+)
+pay.uri                         # upi://pay?pa=shop@okhdfcbank&pn=My%20Shop&am=499.00&cu=INR&...
+save_qr(pay, "order-1042.png")  # or .svg
+html_src = qr_data_uri(pay)     # <img src="...">
+```
+
+### 2. Short links with payment history
+
+```python
+from bitsopay import PaymentLinks, SQLiteStore
+
+with SQLiteStore("payments.db") as store:
+    links = PaymentLinks(store, "https://pay.example.com")
+    link = links.create("shop@okhdfcbank", "My Shop", 499, note="Order 1042", expires_in=3600)
+    print(link.url)             # https://pay.example.com/p/BP684BF1555E4B4907  -> send to the customer
+    link.save("link-qr.png")
+
+    # after YOU confirmed the money in your bank / UPI app:
+    links.mark_paid(link.reference, note="UTR 4123...")
+    links.history(status="pending", limit=20)   # paid | pending | cancelled | expired
+```
+
+### 3. Database-free links
+
+```python
+from bitsopay import StatelessLinks
+
+links = StatelessLinks("shop@okhdfcbank", "My Shop", secret=SECRET, base_url="https://pay.example.com")
+link = links.create(499, expires_in=3600)
+link.url
+```
+
+More in [docs/usage.md](docs/usage.md) and [`examples/`](examples).
+
+## Run the server
+
+```bash
+pip install "bitsopay[server]"
+export BITSOPAY_DB=/var/lib/bitsopay/payments.db
+export BITSOPAY_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+export BITSOPAY_BASE_URL=https://pay.example.com
+gunicorn -c deploy/gunicorn.conf.py "bitsopay.server:create_app()"
+```
+
+Or with Docker: `docker compose up -d` (see [docs/deployment.md](docs/deployment.md)).
+
+```bash
+curl -X POST https://pay.example.com/api/payments \
+  -H "Authorization: Bearer $BITSOPAY_ADMIN_TOKEN" \
+  -d '{"upi_id":"shop@okhdfcbank","payee_name":"My Shop","amount":499,"expires_in":3600}'
+```
+
+| Route | Purpose |
+|---|---|
+| `GET /p/<ref>` | Customer payment page |
+| `GET /p/<ref>/qr.png` · `qr.svg` | QR image |
+| `GET /p/<ref>/status` | Status only (no amount or UPI ID) |
+| `POST /api/payments` | Create a link *(admin)* |
+| `GET /api/payments?status=&limit=&offset=` | History *(admin)* |
+| `GET /api/payments/<ref>` | One record *(admin)* |
+| `POST /api/payments/<ref>/paid` · `/cancel` | Change status *(admin)* |
+| `GET /health` · `/ready` | Liveness and readiness probes |
+
+Full reference: [docs/api.md](docs/api.md).
+
+## Command line
+
+```bash
+bitsopay qr --upi-id shop@okhdfcbank --name "My Shop" --amount 499 -o pay.png
+bitsopay create-link --db payments.db --base-url https://pay.example.com \
+  --upi-id shop@okhdfcbank --name "My Shop" --amount 499 --expires-in 3600
+bitsopay history --db payments.db --status pending
+bitsopay mark-paid BP684BF1555E4B4907 --db payments.db --note "UTR 4123..."
+```
+
+Run `bitsopay --help` for all commands. [docs/cli.md](docs/cli.md) has the details.
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `BITSOPAY_DB` | SQLite path; enables short links, history and the full merchant API |
+| `BITSOPAY_SECRET` | 16+ char secret for signed and database-free links |
+| `BITSOPAY_UPI_ID`, `BITSOPAY_PAYEE_NAME` | Merchant identity for database-free links |
+| `BITSOPAY_ADMIN_TOKEN` | 16+ char bearer token for `/api/*` (API is off without it) |
+| `BITSOPAY_BASE_URL` | Public root URL used in returned links |
+| `BITSOPAY_TRUST_PROXY` | `1` to trust `X-Forwarded-For/Proto` (only behind your own proxy) |
+| `BITSOPAY_LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, ... |
+
+## Security
+
+Links cannot be edited or guessed, secrets are compared in constant time, the page makes no third-party
+requests, and the admin API is throttled against brute force. Read the [threat model](docs/security-model.md)
+before going live, and report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [Usage guide](docs/usage.md) | Library walkthrough |
+| [API reference](docs/api.md) | HTTP routes, errors and status codes |
+| [CLI](docs/cli.md) | Every command |
+| [Architecture](docs/architecture.md) | How the pieces fit |
+| [Deployment](docs/deployment.md) | gunicorn, nginx, Docker, systemd |
+| [Security model](docs/security-model.md) | Threats and limits |
+| [Releasing](docs/releasing.md) | Publishing to PyPI |
+| [Changelog](CHANGELOG.md) | Version history |
+
+## Development
+
+```bash
+git clone https://github.com/Sudharsansm/Bitsopay && cd Bitsopay
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+make check        # ruff, mypy --strict, pytest with coverage
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Bitsophia