Dynamic UPI QR codes and tamper-proof payment links, with no payment gateway.
README · Code of conduct · Contributing · MIT license · Security
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, in the same family as 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,
Decimalamounts, 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,
/healthand/readyprobes, security headers (CSP, HSTS), request IDs, structured logging, admin brute-force throttling. - CLI for scripting and operations.
- One dependency (
segno, pure Python). Python 3.11+. Fully typed (mypy --strict).
Install
pip install bitsopay # library + CLI
pip install "bitsopay[server]" # plus gunicorn for production serving
Quick start
1. A QR code
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
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
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 and examples/.
Run the server
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).
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.
Command line
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 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 before going live, and report vulnerabilities privately as described in SECURITY.md.
Documentation
| Usage guide | Library walkthrough |
| API reference | HTTP routes, errors and status codes |
| CLI | Every command |
| Architecture | How the pieces fit |
| Deployment | gunicorn, nginx, Docker, systemd |
| Security model | Threats and limits |
| Releasing | Publishing to PyPI |
| Changelog | Version history |
Development
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. Participation is governed by the Code of Conduct.
License
MIT © 2026 Bitsophia
Metadata
Release files for bitsopay 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bitsopay-0.1.0.tar.gz | 59.8 kB | With provenance | Details for bitsopay-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bitsopay-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for bitsopay-0.1.0-py3-none-any.whl |
Total release size: 97.2 kB
Release files / bitsopay-0.1.0.tar.gz
| Download URL | bitsopay-0.1.0.tar.gz |
|---|---|
| Size | 59.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5d35f471489274e4ac6cb328946af92582adae47254752117bb41ed2bc3e41d7
|
|
BLAKE2b-256 checksum How to use checksums |
e508530ae407f6c1cb4688cce90c2f3963da3651180a3ca67f3aa24e47a74a39
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / bitsopay-0.1.0-py3-none-any.whl
| Download URL | bitsopay-0.1.0-py3-none-any.whl |
|---|---|
| Size | 37.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7462da6fd98f69a4dbdc6681fbfb26c435be96fca5c0ec1cd08abe985df84fd9
|
|
BLAKE2b-256 checksum How to use checksums |
38d95237052ab2c3d45de6ed5f18c85034c046101ebf7b5d84fa8365d0bdfacc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for bitsopay 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for bitsopay-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.