fampay-verify

A lightweight, secure, and universal Python package to verify FamPay UPI payments automatically by checking Gmail alerts via IMAP.

Compatible with any database (MongoDB, Postgres, MySQL, Supabase, SQLite) and runs in any Python environment (Web apps, Discord Bots, Telegram Bots, CLI tools, FastAPI, Django, etc.).

Features

• Dynamic Amount Verification (No UTR Required): Matches incoming payments automatically by searching for unique decimal amounts (e.g. ₹25.01).
• Manual UTR/TxnID Verification: Fallback to let users paste their 12-digit UTR number manually.
• 15-Minute Expiry Check: Automatically ignores old payment emails to prevent duplicate claims.
• Optional Supabase Logging: Built-in auto-logging and replay attack protection if you choose to connect Supabase, or use your own custom database.
• QR Code Generator: Built-in API to generate UPI payment links and base64 QR code images instantly.
• Sync & Async APIs: Use the synchronous wrapper for simple scripts, or the async version for async frameworks.

---

Installation

pip install fampay-verify

---

Quick Start

1. Generating a Payment QR Code

from fampay_verify import FamPayVerifier, GenerateQrParams

verifier = FamPayVerifier({
    "gmail": "your_email@gmail.com",
    "gmail_app_password": "your_gmail_app_password_without_spaces"
})

# Generate UPI QR Code and Link
qr = verifier.generate_qr(GenerateQrParams(
    upi_id="iflexvault@fam",
    amount="25.01",
    name="iflexvault"
))

print(qr.qr_image)   # Base64 Image string (insert into <img src="..." />)
print(qr.upi_uri)    # upi://pay?pa=iflexvault@fam&pn=...

2. Verifying a Payment (Database-Free / Custom DB)

from fampay_verify import VerifyPaymentParams

# Check for a recent ₹25.01 payment in the inbox
result = verifier.verify_payment(VerifyPaymentParams(
    amount="25.01"
))

if result.verified:
    print(f"Success! Received ₹{result.amount} from {result.sender_name}")
    print(f"UTR Number: {result.utr}")
    
    # Here, you can save the result.utr to MongoDB/Postgres to prevent reuse
else:
    print(f"Failed: {result.message}")

3. Verifying a Payment (with Supabase Auto-Logging)

If you configure Supabase, the package will automatically check for duplicate UTR usage (replay protection) and write transaction logs to your Supabase tables.

verifier = FamPayVerifier({
    "supabase_url": "https://your-supabase.supabase.co",
    "supabase_service_role_key": "your-supabase-service-role-key",
    "gmail": "your_email@gmail.com",
    "gmail_app_password": "your_gmail_app_password"
})

result = verifier.verify_payment(VerifyPaymentParams(
    amount="25.01"
))

4. Using the Async Version (for FastAPI, aiohttp, etc.)

from fampay_verify import AsyncFamPayVerifier, VerifyPaymentParams

verifier = AsyncFamPayVerifier({
    "gmail": "your_email@gmail.com",
    "gmail_app_password": "your_gmail_app_password"
})

# In an async context
result = await verifier.verify_payment(VerifyPaymentParams(amount="25.01"))

---

How to Get Google App Password

For security, Google requires an App Password to log in over IMAP:

1. Go to your Google Account Settings.
2. Navigate to Security and turn on 2-Step Verification.
3. Search for "App passwords" in the top search bar.
4. Create a new App Password (e.g. name it "FamPay Verifier"), copy the 16-character code, and use it in your code config.

---

Supabase Schema (Optional)

If using Supabase, create an api_logs table:

create table api_logs (
  id bigserial primary key,
  created_at timestamp with time zone default timezone('utc'::text, now()),
  user_id text,
  endpoint text,
  status int,
  utr text,
  txn_id text,
  amount numeric
);

---

API Reference

FamPayVerifier(config)

Configuration options:

Key	Type	Required	Description
gmail	str	Yes	Gmail address
gmail_app_password	str	Yes	16-char Google App Password
supabase_url	str	No	Supabase project URL
supabase_service_role_key	str	No	Supabase service role key

verifier.generate_qr(params)

Generates a UPI QR code.

Params (GenerateQrParams):

Key	Type	Required	Description
upi_id	str	Yes	UPI ID (e.g. user@fam)
amount	str/float/int	Yes	Payment amount
name	str	Yes	Recipient name
user_id	str	No	Optional user ID for Supabase logging

Returns (QrResult):

Key	Type	Description
qr_image	str	Base64 data URL (data:image/png;base64,...)
upi_uri	str	UPI payment URI
upi_id	str	UPI ID used
amount	str	Amount as string
name	str	Recipient name
created_at_ist	str	Timestamp in IST

verifier.verify_payment(params)

Verifies a payment by checking Gmail.

Params (VerifyPaymentParams):

Key	Type	Required	Description
amount	str/float/int	Yes	Amount to match
utr	str	No	12-digit UTR number
txnid	str	No	Transaction ID
user_id	str	No	Optional user ID for Supabase logging

Returns (VerificationResult):

Key	Type	Description
verified	bool	Whether payment was verified
transaction_id	str	UTR or TxnID if found
amount	float	Matched amount
utr	str	Extracted UTR
sender_name	str	Sender name from email
payment_time_ist	str	Payment timestamp in IST
message	str	Status message
details	str	Additional details

---

Development

# Clone and install in development mode
git clone https://github.com/iflexvault/fampay-verify
cd fampay-verify
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black fampay_verify examples
ruff check fampay_verify examples

# Type check
mypy fampay_verify

---

License

MIT License - see LICENSE for details.

---

Dev Handle

Created by t.me/iflexvault.