Skip to main content

Bitsopay

Dynamic UPI QR codes and tamper-proof payment links, with no payment gateway.

PyPI Python 3.11+ CI License: MIT Ruff Typed

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, 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, 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="...">
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
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)

Source distribution for bitsopay 0.1.0
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)

Table of built distributions (wheels) for bitsopay 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page