Metadata-Version: 2.4
Name: famgateway
Version: 1.0.0
Summary: Official Python SDK for FamGateway UPI Payment Gateway (by ARYANISPE)
Home-page: https://famgateway.in
Author: ARYANISPE
Author-email: ARYANISPE <support@famgateway.in>
License: MIT
Project-URL: Homepage, https://famgateway.in
Project-URL: Documentation, https://famgateway.in/docs.php
Project-URL: Bug Tracker, https://famgateway.in
Keywords: famgateway,upi,payment-gateway,fampay,telegram-bot,india,npci,aryanispe
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# FamGateway Python SDK ⚡

[![PyPI version](https://img.shields.io/pypi/v/famgateway.svg?color=blue)](https://pypi.org/project/famgateway/)
[![Python versions](https://img.shields.io/pypi/pyversions/famgateway.svg)](https://pypi.org/project/famgateway/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Govt MSME Registered](https://img.shields.io/badge/MSME-UDYAM--BR--28--0050000-blue)](https://famgateway.in)

The official Python client library for **[FamGateway](https://famgateway.in)** — 100% Free, Zero-Fee Peer-to-Peer UPI Payment Gateway for Indian Developers and Businesses.

---

## ✨ Features

- ⚡ **Instant Dynamic UPI QR Codes** — Get direct QR image URLs (`qr_url`) to send directly in Telegram Bots or apps.
- 📲 **Deep UPI Intent Links** — `upi://pay?...` URLs for 1-tap payments in PhonePe, Google Pay, and Paytm.
- 🤖 **Telegram Bot Friendly** — Send QR codes directly to users inside Telegram chats without external browser redirects.
- 🛡️ **Zero Transaction Fees** — 100% peer-to-peer settlement directly into your FamPay / UPI ID.
- 🔔 **Instant Webhooks & Polling** — Automated payment reconciliation via webhooks and status API.

---

## 📦 Installation

```bash
pip install famgateway
```

---

## 🚀 Quickstart (3 Lines of Code)

```python
from famgateway import FamGateway

# 1. Initialize client with your API Key
fg = FamGateway(api_key="your_famgateway_api_key")

# 2. Create a dynamic UPI payment order
order = fg.create_order(
    amount=100.0,
    customer_name="Aryan Gupta",
    customer_phone="9876543210"
)

print("Order ID:", order.order_id)
print("Payable Amount: ₹", order.payable_amount)
print("QR Code Image URL:", order.qr_url)
print("Deep UPI Intent:", order.upi_intent)
print("Hosted Checkout URL:", order.checkout_url)

# 3. Check order payment status
status = fg.get_status(order.order_id)
if status.is_paid:
    print(f"Payment Captured! UTR: {status.utr}")
```

---

## 🤖 Telegram Bot Integration Example

Use `famgateway` to collect payments directly inside Telegram without any website redirect!

```python
import telebot
from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton
from famgateway import FamGateway

bot = telebot.TeleBot("YOUR_TELEGRAM_BOT_TOKEN")
fg = FamGateway(api_key="YOUR_FAMGATEWAY_API_KEY")

@bot.message_handler(commands=['buy'])
def handle_buy(message):
    # 1. Create UPI payment order for ₹50
    order = fg.create_order(
        amount=50.0,
        customer_name=f"{message.from_user.first_name} ({message.from_user.id})"
    )

    # 2. Create inline pay button
    markup = InlineKeyboardMarkup()
    markup.row(
        InlineKeyboardButton("📲 Pay via UPI App", url=order.upi_intent),
        InlineKeyboardButton("🔄 Check Status", callback_data=f"check_{order.order_id}")
    )

    # 3. Send QR image directly in chat!
    bot.send_photo(
        chat_id=message.chat.id,
        photo=order.qr_url,
        caption=f"⚡ *Scan to Pay ₹{order.payable_amount}*\n\nOrder ID: `{order.order_id}`",
        parse_mode="Markdown",
        reply_markup=markup
    )

@bot.callback_query_handler(func=lambda call: call.data.startswith("check_"))
def handle_status(call):
    order_id = call.data.split("_")[1]
    status = fg.get_status(order_id)

    if status.is_paid:
        bot.answer_callback_query(call.id, "✅ Payment Verified!", show_alert=True)
        bot.send_message(call.message.chat.id, f"🎉 Payment received! UTR: `{status.utr}`")
    else:
        bot.answer_callback_query(call.id, "⏳ Payment pending. Please complete the UPI payment.", show_alert=True)

bot.infinity_polling()
```

---

## 📚 API Reference

### `FamGateway(api_key, base_url="https://famgateway.in", timeout=15)`
Initializes the FamGateway client.

### `fg.create_order(amount, customer_name=None, customer_email=None, customer_phone=None, redirect_url=None, webhook_url=None)`
Creates a new payment order and generates dynamic UPI QR details.

**Returns `OrderResponse` object:**
- `order.order_id` *(str)*: Unique order reference (e.g. `fg_J2KVI0O8`)
- `order.amount` *(float)*: Base order amount
- `order.payable_amount` *(float)*: Reconciled payable amount
- `order.qr_url` *(str)*: Direct URL of the QR code image
- `order.upi_intent` *(str)*: Deep link (`upi://pay?...`) for opening UPI apps
- `order.checkout_url` *(str)*: Hosted web checkout URL
- `order.upi_id` *(str)*: Receiver UPI ID

### `fg.get_status(order_id)`
Checks payment status for an order.

**Returns `OrderStatus` object:**
- `status.status` *(str)*: `'success'`, `'pending'`, or `'expired'`
- `status.is_paid` *(bool)*: `True` if payment captured successfully
- `status.is_pending` *(bool)*: `True` if awaiting customer payment
- `status.utr` *(str|None)*: Bank 12-digit UTR / RRN reference
- `status.transaction_id` *(str|None)*: FamPay transaction reference ID
- `status.sender_name` *(str|None)*: Name of payer

---

## 🏢 About & Legal

FamGateway is a developer-focused payment orchestration platform operated by **ARYANISPE**.
- **Govt. MSME Registration:** `UDYAM-BR-28-0050000` (Ministry of MSME, Govt. of India)
- **Website:** [https://famgateway.in](https://famgateway.in)
- **Support:** [support@famgateway.in](mailto:support@famgateway.in)

## 📄 License
MIT License. Free for commercial and private use.
