Metadata-Version: 2.4
Name: fampay-verify
Version: 1.0.6
Summary: FamPay payment verification utility and QR generator for Python
License-Expression: MIT
Project-URL: Homepage, https://github.com/iflexvault/fampay-verify
Project-URL: Repository, https://github.com/iflexvault/fampay-verify
Project-URL: Issues, https://github.com/iflexvault/fampay-verify/issues
Keywords: fampay,upi,payment,verification,qr-code,imap,gmail
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qrcode>=7.4
Requires-Dist: imap-tools>=0.55
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Provides-Extra: supabase
Requires-Dist: supabase>=2.0; extra == "supabase"
Provides-Extra: pil
Requires-Dist: pillow>=9.1.0; extra == "pil"
Dynamic: license-file

# fampay-verify

[![PyPI version](https://img.shields.io/pypi/v/fampay-verify.svg?style=flat-square)](https://pypi.org/project/fampay-verify/)
[![PyPI downloads](https://img.shields.io/pypi/dm/fampay-verify.svg?style=flat-square)](https://pypi.org/project/fampay-verify/)
[![Python versions](https://img.shields.io/pypi/pyversions/fampay-verify.svg?style=flat-square)](https://pypi.org/project/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

```bash
pip install fampay-verify
```

---

## Quick Start

### 1. Generating a Payment QR Code

```python
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)

```python
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.

```python
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.)

```python
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](https://myaccount.google.com/).
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:

```sql
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

```bash
# 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](LICENSE) for details.

---

## Dev Handle

Created by `t.me/iflexvault`.
