bitsopay 0.1.0__py3-none-any.whl

bitsopay/__init__.py

@@ -0,0 +1,64 @@
+"""Bitsopay: dynamic UPI QR codes and signed payment links.
+
+>>> from bitsopay import UPIPayment, qr_png, create_payment_link
+>>> pay = UPIPayment(upi_id="shop@okhdfcbank", payee_name="My Shop", amount=499)
+>>> pay.uri
+'upi://pay?pa=shop@okhdfcbank&pn=My%20Shop&am=499.00&cu=INR'
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .exceptions import (
+    BitsoPayError,
+    DuplicateReferenceError,
+    InvalidStateError,
+    LinkExpiredError,
+    NotFoundError,
+    SignatureError,
+    ValidationError,
+)
+from .link import create_payment_link, parse_payment_link, verify_payment_link
+from .models import UPIPayment
+from .page import render_payment_page
+from .qr import qr_data_uri, qr_png, qr_svg, save_qr
+from .session import SessionQR, create_session_qr
+from .shortlink import PaymentLink, PaymentLinks
+from .stateless import StatelessLink, StatelessLinks
+from .store import MemoryStore, PaymentRecord, PaymentStore, SQLiteStore
+from .upi import build_app_uri, build_upi_uri
+from .validators import new_reference
+
+__all__ = [
+    "BitsoPayError",
+    "DuplicateReferenceError",
+    "InvalidStateError",
+    "LinkExpiredError",
+    "MemoryStore",
+    "NotFoundError",
+    "PaymentLink",
+    "PaymentLinks",
+    "PaymentRecord",
+    "PaymentStore",
+    "SQLiteStore",
+    "SessionQR",
+    "SignatureError",
+    "StatelessLink",
+    "StatelessLinks",
+    "UPIPayment",
+    "ValidationError",
+    "__version__",
+    "build_app_uri",
+    "build_upi_uri",
+    "create_payment_link",
+    "create_session_qr",
+    "new_reference",
+    "parse_payment_link",
+    "qr_data_uri",
+    "qr_png",
+    "qr_svg",
+    "render_payment_page",
+    "save_qr",
+    "verify_payment_link",
+]

bitsopay/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m bitsopay`` runs the command line interface."""
+
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

bitsopay/cli.py

@@ -0,0 +1,245 @@
+"""Command line interface.
+
+``bitsopay qr|uri|link|session-qr|page``   stateless helpers
+``bitsopay create-link|history|show|mark-paid|cancel``   short links + history (SQLite)
+``bitsopay serve``   run the payment server
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import datetime
+from typing import List, Optional
+
+from . import __version__
+from .exceptions import BitsoPayError
+from .link import create_payment_link
+from .models import UPIPayment
+from .page import render_payment_page
+from .qr import save_qr
+from .session import create_session_qr
+from .shortlink import PaymentLinks
+from .stateless import StatelessLinks
+from .store import SQLiteStore
+
+
+def _add_payment_args(p: argparse.ArgumentParser, ref: bool = True) -> None:
+    p.add_argument("--upi-id", required=True, help="Merchant UPI ID, e.g. shop@okhdfcbank")
+    p.add_argument("--name", required=True, help="Payee / merchant name")
+    p.add_argument("--amount", help="Amount in INR (omit for open amount)")
+    p.add_argument("--note", help="Transaction note (max 80 chars)")
+    if ref:
+        p.add_argument("--ref", help="Transaction reference / order id")
+    p.add_argument("--mcc", help="4-digit merchant category code")
+
+
+def _payment(a: argparse.Namespace) -> UPIPayment:
+    return UPIPayment(
+        upi_id=a.upi_id,
+        payee_name=a.name,
+        amount=a.amount,
+        note=a.note,
+        reference=getattr(a, "ref", None),
+        merchant_code=a.mcc,
+    )
+
+
+def _secret(a: argparse.Namespace) -> str:
+    secret = a.secret or os.environ.get("BITSOPAY_SECRET")
+    if not secret:
+        raise BitsoPayError("Provide --secret or set BITSOPAY_SECRET")
+    return secret
+
+
+def _db_arg(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--db", help="SQLite file (or $BITSOPAY_DB)")
+
+
+def _links(a: argparse.Namespace, opened: List[SQLiteStore]) -> PaymentLinks:
+    path = a.db or os.environ.get("BITSOPAY_DB")
+    if not path:
+        raise BitsoPayError("Provide --db or set BITSOPAY_DB")
+    store = SQLiteStore(path)
+    opened.append(store)  # closed by main() when the command finishes
+    return PaymentLinks(store, getattr(a, "base_url", None) or os.environ.get("BITSOPAY_BASE_URL"))
+
+
+def _fmt_time(ts: Optional[int]) -> str:
+    return "-" if ts is None else datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bitsopay", description="UPI QR codes and payment links")
+    parser.add_argument("--version", action="version", version=f"bitsopay {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    qr = sub.add_parser("qr", help="Write a QR code image (.png or .svg)")
+    _add_payment_args(qr)
+    qr.add_argument("-o", "--output", required=True)
+
+    uri = sub.add_parser("uri", help="Print the upi:// deep link")
+    _add_payment_args(uri)
+
+    link = sub.add_parser("link", help="Create a signed https payment link (data in URL)")
+    _add_payment_args(link)
+    link.add_argument("--base-url", required=True, help="e.g. https://pay.example.com/pay")
+    link.add_argument("--secret", help="Signing secret (or $BITSOPAY_SECRET)")
+    link.add_argument("--expires-in", type=int, default=86400, help="Seconds until expiry (0 = never)")
+
+    sess = sub.add_parser("session-qr", help="Write an expiring QR using a signed link")
+    _add_payment_args(sess)
+    sess.add_argument("--base-url", required=True, help="e.g. https://pay.example.com/pay")
+    sess.add_argument("--secret", help="Signing secret (or $BITSOPAY_SECRET)")
+    sess.add_argument("--expires-in", type=int, default=300, help="Session length in seconds (default 300)")
+    sess.add_argument("-o", "--output", required=True)
+
+    page = sub.add_parser("page", help="Write a standalone HTML payment page")
+    _add_payment_args(page)
+    page.add_argument("-o", "--output", required=True)
+
+    # -- secure short links ------------------------------------------------
+    cl = sub.add_parser("create-link", help="Create a secure short link (reference code only in URL)")
+    _add_payment_args(cl, ref=False)
+    _db_arg(cl)
+    cl.add_argument("--base-url", help="Public server root, e.g. https://pay.example.com (or $BITSOPAY_BASE_URL)")
+    cl.add_argument("--expires-in", type=int, default=86400, help="Seconds until expiry (0 = never)")
+    cl.add_argument("-o", "--output", help="Also write a QR of the short link (.png / .svg)")
+
+    ql = sub.add_parser("quick-link", help="Create a database-free short link (no storage needed)")
+    ql.add_argument("--upi-id", required=True)
+    ql.add_argument("--name", required=True)
+    ql.add_argument("--amount", help="Amount in INR (omit for open amount)")
+    ql.add_argument("--base-url", required=True, help="Public server root, e.g. https://pay.example.com")
+    ql.add_argument("--secret", help="Signing secret (or $BITSOPAY_SECRET)")
+    ql.add_argument("--expires-in", type=int, default=86400, help="Seconds until expiry (0 = never)")
+    ql.add_argument("-o", "--output", help="Also write a QR of the link (.png / .svg)")
+
+    hist = sub.add_parser("history", help="List payment history")
+    _db_arg(hist)
+    hist.add_argument("--status", choices=["pending", "paid", "cancelled", "expired"])
+    hist.add_argument("--limit", type=int, default=20)
+
+    show = sub.add_parser("show", help="Show one payment")
+    _db_arg(show)
+    show.add_argument("reference")
+
+    paid = sub.add_parser("mark-paid", help="Mark a payment as paid after verifying it manually")
+    _db_arg(paid)
+    paid.add_argument("reference")
+    paid.add_argument("--note", help="e.g. the UPI transaction id from your bank statement")
+
+    cancel = sub.add_parser("cancel", help="Cancel a pending payment link")
+    _db_arg(cancel)
+    cancel.add_argument("reference")
+
+    serve = sub.add_parser("serve", help="Run a dev server for payment links")
+    serve.add_argument("--secret", help="Signing secret for legacy signed links (or $BITSOPAY_SECRET)")
+    _db_arg(serve)
+    serve.add_argument("--upi-id", help="Merchant UPI ID for database-free links (or $BITSOPAY_UPI_ID)")
+    serve.add_argument("--name", help="Merchant name for database-free links (or $BITSOPAY_PAYEE_NAME)")
+    serve.add_argument("--admin-token", help="Merchant API token (or $BITSOPAY_ADMIN_TOKEN)")
+    serve.add_argument("--base-url", help="Public root URL (or $BITSOPAY_BASE_URL)")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8080)
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    opened: List[SQLiteStore] = []
+    try:
+        if args.cmd == "qr":
+            print(save_qr(_payment(args), args.output))
+        elif args.cmd == "uri":
+            print(_payment(args).uri)
+        elif args.cmd == "link":
+            exp = args.expires_in or None
+            print(create_payment_link(args.base_url, _payment(args), _secret(args), expires_in=exp))
+        elif args.cmd == "session-qr":
+            sq = create_session_qr(args.base_url, _payment(args), _secret(args), expires_in=args.expires_in)
+            sq.save(args.output)
+            print(f"{args.output}  (valid for {args.expires_in}s)\n{sq.url}")
+        elif args.cmd == "page":
+            with open(args.output, "w", encoding="utf-8") as fh:
+                fh.write(render_payment_page(_payment(args)))
+            print(args.output)
+        elif args.cmd == "create-link":
+            links = _links(args, opened)
+            new = links.create(
+                args.upi_id,
+                args.name,
+                args.amount,
+                note=args.note,
+                merchant_code=args.mcc,
+                expires_in=args.expires_in or None,
+            )
+            print(f"reference: {new.reference}\nurl:       {new.url}\nexpires:   {_fmt_time(new.expires_at)}")
+            if args.output:
+                print(f"qr:        {new.save(args.output)}")
+        elif args.cmd == "quick-link":
+            sl = StatelessLinks(args.upi_id, args.name, _secret(args), args.base_url).create(
+                args.amount, expires_in=args.expires_in or None
+            )
+            print(f"reference: {sl.reference}\nurl:       {sl.url}\nexpires:   {_fmt_time(sl.expires_at)}")
+            if args.output:
+                print(f"qr:        {sl.save(args.output)}")
+        elif args.cmd == "history":
+            links = _links(args, opened)
+            rows = links.history(args.status, args.limit)
+            if not rows:
+                print("No payments found.")
+            now = links.clock()
+            for r in rows:
+                amt = "open" if r.amount is None else f"{r.amount:.2f}"
+                print(
+                    f"{r.reference}  {r.effective_status(now):<9}  {amt:>10}  {r.payee_name}  "
+                    f"created {_fmt_time(r.created_at)}  views {r.views}"
+                )
+        elif args.cmd == "show":
+            links = _links(args, opened)
+            rec = links.get(args.reference)
+            if rec is None:
+                raise BitsoPayError(f"No payment with reference {args.reference}")
+            for k, v in rec.to_dict(links.clock()).items():
+                print(f"{k:<14} {v}")
+        elif args.cmd == "mark-paid":
+            rec = _links(args, opened).mark_paid(args.reference, args.note)
+            print(f"{rec.reference} marked paid at {_fmt_time(rec.paid_at)}")
+        elif args.cmd == "cancel":
+            rec = _links(args, opened).cancel(args.reference)
+            print(f"{rec.reference} cancelled")
+        elif args.cmd == "serve":
+            from .server import serve
+
+            path = args.db or os.environ.get("BITSOPAY_DB")
+            secret = args.secret or os.environ.get("BITSOPAY_SECRET")
+            upi = args.upi_id or os.environ.get("BITSOPAY_UPI_ID")
+            pname = args.name or os.environ.get("BITSOPAY_PAYEE_NAME")
+            if not path and not secret:
+                raise BitsoPayError("Provide --db (short links) and/or --secret (signed / database-free links)")
+            stateless = StatelessLinks(upi, pname, secret) if (upi and pname and secret) else None
+            store = SQLiteStore(path) if path else None
+            if store is not None:
+                opened.append(store)  # closed when the server stops
+            serve(
+                secret,
+                args.host,
+                args.port,
+                store=store,
+                admin_token=args.admin_token or os.environ.get("BITSOPAY_ADMIN_TOKEN"),
+                base_url=args.base_url or os.environ.get("BITSOPAY_BASE_URL"),
+                stateless=stateless,
+            )
+    except BitsoPayError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    finally:
+        for opened_store in opened:
+            opened_store.close()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

bitsopay/exceptions.py

@@ -0,0 +1,31 @@
+"""Exception hierarchy for bitsopay."""
+
+from __future__ import annotations
+
+
+class BitsoPayError(Exception):
+    """Base class for all bitsopay errors."""
+
+
+class ValidationError(BitsoPayError, ValueError):
+    """Raised when a UPI ID, amount or other field is invalid."""
+
+
+class SignatureError(BitsoPayError):
+    """Raised when a signed payment link has a missing or invalid signature."""
+
+
+class LinkExpiredError(BitsoPayError):
+    """Raised when a signed payment link is past its expiry time."""
+
+
+class NotFoundError(BitsoPayError):
+    """Raised when a payment reference does not exist."""
+
+
+class InvalidStateError(BitsoPayError):
+    """Raised for a status change that is not allowed (e.g. cancelling a paid payment)."""
+
+
+class DuplicateReferenceError(BitsoPayError):
+    """Raised by a store when a reference already exists."""

bitsopay/link.py

@@ -0,0 +1,122 @@
+"""Signed, tamper-proof web payment links.
+
+A *payment link* is a normal HTTPS URL the merchant shares (WhatsApp, SMS, email).
+It carries the UPI ID, amount, etc. plus an HMAC-SHA256 signature and an expiry, so
+a customer cannot edit the amount in the URL. Open on a phone, the page offers a
+"Pay with UPI app" button; on desktop it shows a QR code to scan.
+
+Serve the links with :mod:`bitsopay.server` (a ready WSGI app) or render the page
+yourself with :func:`bitsopay.page.render_payment_page`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Dict, List, Mapping, Optional, Tuple, Union
+from urllib.parse import parse_qs, urlencode, urlparse
+
+from .exceptions import LinkExpiredError, SignatureError, ValidationError
+from .models import UPIPayment
+
+_SIGNED_KEYS = ("pa", "pn", "am", "tn", "tr", "mc", "cu", "exp")
+DEFAULT_EXPIRY_SECONDS = 24 * 60 * 60
+
+
+def _secret_bytes(secret: Union[str, bytes]) -> bytes:
+    key = secret.encode("utf-8") if isinstance(secret, str) else secret
+    if len(key) < 16:
+        raise ValidationError("Signing secret must be at least 16 bytes long")
+    return key
+
+
+def _fields(payment: UPIPayment, exp: Optional[int]) -> Dict[str, str]:
+    data: Dict[str, str] = {"pa": payment.upi_id, "pn": payment.payee_name, "cu": payment.currency}
+    if payment.amount is not None:
+        data["am"] = f"{payment.amount:.2f}"
+    if payment.note:
+        data["tn"] = payment.note
+    if payment.reference:
+        data["tr"] = payment.reference
+    if payment.merchant_code:
+        data["mc"] = payment.merchant_code
+    if exp is not None:
+        data["exp"] = str(exp)
+    return data
+
+
+def _sign(fields: Mapping[str, str], secret: Union[str, bytes]) -> str:
+    message = "\n".join(f"{k}={fields[k]}" for k in _SIGNED_KEYS if k in fields)
+    return hmac.new(_secret_bytes(secret), message.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def create_payment_link(
+    base_url: str,
+    payment: UPIPayment,
+    secret: Union[str, bytes],
+    *,
+    expires_in: Optional[int] = DEFAULT_EXPIRY_SECONDS,
+    now: Optional[float] = None,
+) -> str:
+    """Return ``base_url?...&sig=...`` for ``payment``.
+
+    ``base_url`` is the full URL of your payment page, e.g. ``https://pay.example.com/pay``.
+    Pass ``expires_in=None`` for a link that never expires.
+    """
+    if not base_url.lower().startswith(("https://", "http://")):
+        raise ValidationError("base_url must start with http:// or https://")
+    exp = None if expires_in is None else int((now if now is not None else time.time()) + expires_in)
+    fields = _fields(payment, exp)
+    fields["sig"] = _sign(fields, secret)
+    sep = "&" if "?" in base_url else "?"
+    return f"{base_url}{sep}{urlencode(fields)}"
+
+
+def verify_payment_link(
+    link_or_query: str,
+    secret: Union[str, bytes],
+    *,
+    now: Optional[float] = None,
+) -> Tuple[UPIPayment, Optional[int]]:
+    """Verify signature and expiry; return ``(payment, expires_at_unix_or_None)``.
+
+    Accepts a full URL or just the query string. Raises :class:`SignatureError`
+    or :class:`LinkExpiredError`.
+    """
+    query = urlparse(link_or_query).query if "?" in link_or_query or "://" in link_or_query else link_or_query
+    raw: Dict[str, List[str]] = parse_qs(query, keep_blank_values=False)
+    fields = {k: vals[0] for k, vals in raw.items() if k in _SIGNED_KEYS and vals}
+    sig = (raw.get("sig") or [""])[0]
+    if not sig or "pa" not in fields:
+        raise SignatureError("Missing signature")
+    if not hmac.compare_digest(sig, _sign(fields, secret)):
+        raise SignatureError("Invalid signature")
+    exp: Optional[int] = None
+    if "exp" in fields:
+        try:
+            exp = int(fields["exp"])
+        except ValueError:
+            raise SignatureError("Invalid expiry") from None
+        if (now if now is not None else time.time()) > exp:
+            raise LinkExpiredError("This payment link has expired")
+    payment = UPIPayment(
+        upi_id=fields["pa"],
+        payee_name=fields.get("pn", ""),
+        amount=fields.get("am"),
+        note=fields.get("tn"),
+        reference=fields.get("tr"),
+        merchant_code=fields.get("mc"),
+        currency=fields.get("cu", "INR"),
+    )
+    return payment, exp
+
+
+def parse_payment_link(
+    link_or_query: str,
+    secret: Union[str, bytes],
+    *,
+    now: Optional[float] = None,
+) -> UPIPayment:
+    """Like :func:`verify_payment_link` but returns only the :class:`UPIPayment`."""
+    return verify_payment_link(link_or_query, secret, now=now)[0]

bitsopay/models.py

@@ -0,0 +1,57 @@
+"""The :class:`UPIPayment` value object."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Optional
+
+from . import validators as v
+from .exceptions import ValidationError
+
+DEFAULT_MAX_AMOUNT = Decimal("10000000.00")  # sanity cap: 1 crore INR
+
+
+@dataclass(frozen=True)
+class UPIPayment:
+    """A validated request to pay ``amount`` INR to ``upi_id``.
+
+    ``amount=None`` produces an *open amount* request where the payer types the amount.
+    """
+
+    upi_id: str
+    payee_name: str
+    amount: Optional[v.Number] = None
+    note: Optional[str] = None
+    reference: Optional[str] = None
+    merchant_code: Optional[str] = None
+    currency: str = "INR"
+    max_amount: Decimal = DEFAULT_MAX_AMOUNT
+
+    def __post_init__(self) -> None:
+        name = v.validate_text(self.payee_name, "payee_name", v.MAX_NAME_LEN)
+        if not name:
+            raise ValidationError("payee_name is required")
+        if self.currency != "INR":
+            raise ValidationError("Only INR is supported by UPI")
+        max_amount = Decimal(str(self.max_amount))
+        object.__setattr__(self, "max_amount", max_amount)
+        object.__setattr__(self, "upi_id", v.validate_vpa(self.upi_id))
+        object.__setattr__(self, "payee_name", name)
+        object.__setattr__(self, "amount", v.validate_amount(self.amount, max_amount))
+        object.__setattr__(self, "note", v.validate_text(self.note, "note", v.MAX_NOTE_LEN))
+        object.__setattr__(self, "reference", v.validate_reference(self.reference))
+        object.__setattr__(self, "merchant_code", v.validate_mcc(self.merchant_code))
+
+    @property
+    def uri(self) -> str:
+        """The ``upi://pay`` deep link / QR payload."""
+        from .upi import build_upi_uri
+
+        return build_upi_uri(self)
+
+    def with_reference(self, reference: Optional[str] = None) -> UPIPayment:
+        """Return a copy with a (generated, if omitted) transaction reference."""
+        from dataclasses import replace
+
+        return replace(self, reference=reference or v.new_reference())

bitsopay/page.py

@@ -0,0 +1,133 @@
+"""Self-contained HTML payment page (QR for desktop, app buttons for mobile)."""
+
+from __future__ import annotations
+
+from html import escape
+from typing import Optional
+
+from .models import UPIPayment
+from .qr import qr_data_uri
+from .upi import APP_SCHEMES, build_app_uri
+
+_APP_LABELS = {"gpay": "Google Pay", "phonepe": "PhonePe", "paytm": "Paytm"}
+
+_TEMPLATE = """<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'">
+<title>Pay {payee}</title>
+<style>
+  :root {{ color-scheme: light dark; --fg:#111827; --muted:#6b7280; --bg:#f3f4f6; --card:#fff; --accent:#4f46e5; }}
+  @media (prefers-color-scheme: dark) {{ :root {{ --fg:#f9fafb; --muted:#9ca3af; --bg:#111827; --card:#1f2937; }} }}
+  * {{ box-sizing: border-box; }}
+  body {{ margin:0; min-height:100vh; display:grid; place-items:center; padding:16px;
+         font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; background:var(--bg); color:var(--fg); }}
+  .card {{ width:100%; max-width:380px; background:var(--card); border-radius:16px; padding:24px; text-align:center;
+          box-shadow:0 8px 30px rgba(0,0,0,.12); }}
+  .payee {{ font-size:14px; color:var(--muted); margin:0; }}
+  .name {{ font-size:20px; font-weight:600; margin:2px 0 12px; word-break:break-word; }}
+  .amount {{ font-size:36px; font-weight:700; margin:4px 0 2px; }}
+  .note {{ color:var(--muted); font-size:14px; margin:0 0 16px; word-break:break-word; }}
+  .qr {{ width:240px; max-width:100%; height:auto; border-radius:8px; background:#fff; padding:8px; }}
+  .btn {{ display:block; margin:10px 0 0; padding:14px; border-radius:12px; text-decoration:none; font-weight:600;
+         background:var(--accent); color:#fff; }}
+  .btn.alt {{ background:transparent; color:var(--accent); border:1px solid var(--accent); }}
+  .upi {{ font-size:13px; color:var(--muted); margin-top:16px; word-break:break-all; }}
+  .hint {{ font-size:12px; color:var(--muted); margin-top:12px; }}
+  .timer {{ font-size:13px; color:var(--muted); margin:0 0 12px; }}
+  .expired .pay {{ display:none; }}
+  .expired-msg {{ display:none; color:#dc2626; font-weight:600; margin:16px 0; }}
+  .expired .expired-msg {{ display:block; }}
+</style>
+</head>
+<body>
+<main class="card" id="card">
+  <p class="payee">Pay to</p>
+  <h1 class="name">{payee}</h1>
+  <div class="amount">{amount}</div>
+  {note}
+  {timer}
+  <div class="pay">
+  <img class="qr" src="{qr}" alt="UPI QR code for {payee}" width="240" height="240">
+  <a class="btn" href="{uri}">Pay with any UPI app</a>
+  {app_buttons}
+  <div class="upi">UPI ID: {upi_id}</div>
+  </div>
+  <div class="expired-msg">This payment session has ended. Please request a new link.</div>
+  {ref}
+  <div class="hint">Scan the QR with any UPI app, or tap a button on your phone.</div>
+</main>
+{script}
+</body>
+</html>
+"""
+
+
+_SCRIPT = """<script>
+(function(){{
+  var end = {exp} * 1000, card = document.getElementById("card"), t = document.getElementById("timer");
+  function tick(){{
+    var left = Math.floor((end - Date.now()) / 1000);
+    if (left <= 0) {{ card.className += " expired"; if (t) t.textContent = "Session ended"; return; }}
+    if (t) t.textContent = "Session ends in " + Math.floor(left/60) + ":" + ("0"+(left%60)).slice(-2);
+    setTimeout(tick, 1000);
+  }}
+  tick();
+}})();
+</script>"""
+
+
+def render_payment_page(payment: UPIPayment, expires_at: Optional[int] = None) -> str:
+    """Return a complete, escaped HTML page for ``payment``.
+
+    If ``expires_at`` (unix seconds) is given, the page shows a countdown and hides the
+    QR and pay buttons when the session ends.
+    """
+    amount = f"&#8377;{payment.amount:,.2f}" if payment.amount is not None else "Enter amount in app"
+    apps = "\n  ".join(
+        f'<a class="btn alt" href="{escape(build_app_uri(payment, app), quote=True)}">{escape(_APP_LABELS[app])}</a>'
+        for app in APP_SCHEMES
+    )
+    return _TEMPLATE.format(
+        payee=escape(payment.payee_name),
+        amount=amount,
+        note=f'<p class="note">{escape(payment.note)}</p>' if payment.note else "",
+        qr=qr_data_uri(payment),
+        uri=escape(payment.uri, quote=True),
+        app_buttons=apps,
+        upi_id=escape(payment.upi_id),
+        timer='<p class="timer" id="timer"></p>' if expires_at is not None else "",
+        script=_SCRIPT.format(exp=int(expires_at)) if expires_at is not None else "",
+        ref=f'<div class="upi">Ref: {escape(payment.reference)}</div>' if payment.reference else "",
+    )
+
+
+_MESSAGE = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<title>{title}</title>
+<style>
+  :root {{ color-scheme: light dark; }}
+  body {{ margin:0; min-height:100vh; display:grid; place-items:center; padding:16px;
+         font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; background:#f3f4f6; color:#111827; }}
+  @media (prefers-color-scheme: dark) {{ body {{ background:#111827; color:#f9fafb; }} .card {{ background:#1f2937 !important; }} }}
+  .card {{ max-width:380px; width:100%; background:#fff; border-radius:16px; padding:28px; text-align:center;
+          box-shadow:0 8px 30px rgba(0,0,0,.12); }}
+  h1 {{ font-size:20px; margin:0 0 8px; }} p {{ margin:6px 0; color:#6b7280; }}
+</style></head>
+<body><main class="card"><h1>{title}</h1><p>{message}</p>{ref}</main></body></html>
+"""
+
+
+def render_message_page(title: str, message: str, reference: Optional[str] = None) -> str:
+    """A small status page (paid / expired / cancelled / not found)."""
+    return _MESSAGE.format(
+        title=escape(title),
+        message=escape(message),
+        ref=f"<p>Ref: {escape(reference)}</p>" if reference else "",
+    )