neonpay

Name	neonpay JSON
Version	2.5.0 JSON
	download
home_page	https://github.com/Abbasxan/neonpay
Summary	Modern Telegram Stars payment library with multi-bot support and enhanced security
upload_time	2025-09-06 15:04:00
maintainer	None
docs_url	None
author	Abbas Sultanov
requires_python	>=3.9
license	MIT
keywords	telegram telegram-bot payment stars xtr crypto pyrogram aiogram python-telegram-bot telebot webhook security validation async payment-processing
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # NEONPAY - Modern Telegram Stars Payment Library

[![PyPI version](https://badge.fury.io/py/neonpay.svg)](https://badge.fury.io/py/neonpay)
[![Python Support](https://img.shields.io/pypi/pyversions/neonpay.svg)](https://pypi.org/project/neonpay/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**NEONPAY** is a modern, universal payment processing library for Telegram bots that makes integrating Telegram Stars payments incredibly simple. With support for all major bot libraries and a clean, intuitive API, you can add payments to your bot in just a few lines of code.

## ✨ Features

- 🚀 **Universal Support** - Works with Pyrogram, Aiogram, python-telegram-bot, pyTelegramBotAPI, and raw Bot API
- 💫 **Telegram Stars Integration** - Native support for Telegram's XTR currency
- 🎨 **Custom Payment Stages** - Create branded payment experiences with custom logos and descriptions
- 🔧 **Simple Setup** - Get started with just 2-3 lines of code
- 📱 **Modern Architecture** - Built with async/await and type hints
- 🛡️ **Error Handling** - Comprehensive error handling and validation
- 📦 **Zero Dependencies** - Only requires your chosen bot library

## 🚀 Quick Start

### Installation

```bash
pip install neonpay
```

### Basic Usage

```python
from neonpay import create_neonpay, PaymentStage

# Works with any bot library - automatic detection!
neonpay = create_neonpay(your_bot_instance)

# Create a payment stage
stage = PaymentStage(
    title="Premium Features",
    description="Unlock all premium features",
    price=100,  # 100 Telegram Stars
    photo_url="https://example.com/logo.png"
)

# Add the payment stage
neonpay.create_payment_stage("premium", stage)

# Send payment to user
await neonpay.send_payment(user_id=12345, stage_id="premium")

# Handle successful payments
@neonpay.on_payment
async def handle_payment(result):
    print(f"Payment received: {result.amount} stars from user {result.user_id}")
```

## 📚 Library Support

NEONPAY automatically detects your bot library and creates the appropriate adapter:

### Pyrogram

```python
from pyrogram import Client
from neonpay import create_neonpay

app = Client("my_bot", bot_token="YOUR_TOKEN")
neonpay = create_neonpay(app)
```

### Aiogram

```python
from aiogram import Bot, Dispatcher
from neonpay import create_neonpay

bot = Bot(token="YOUR_TOKEN")
dp = Dispatcher()
neonpay = create_neonpay(bot, dp)  # Pass dispatcher for aiogram
```

### python-telegram-bot

```python
from telegram.ext import Application
from neonpay import create_neonpay

application = Application.builder().token("YOUR_TOKEN").build()
neonpay = create_neonpay(application)
```

### pyTelegramBotAPI

```python
import telebot
from neonpay import create_neonpay

bot = telebot.TeleBot("YOUR_TOKEN")
neonpay = create_neonpay(bot)
```

### Raw Bot API

```python
from neonpay import RawAPIAdapter, NeonPayCore

adapter = RawAPIAdapter("YOUR_TOKEN", webhook_url="https://yoursite.com/webhook")
neonpay = NeonPayCore(adapter)
```

## 🎯 Advanced Usage

### Custom Payment Stages

```python
from neonpay import PaymentStage

# Create detailed payment stage
premium_stage = PaymentStage(
    title="Premium Subscription",
    description="Get access to exclusive features and priority support",
    price=500,  # 500 Telegram Stars
    label="Premium Plan",
    photo_url="https://yoursite.com/premium-logo.png",
    payload={"plan": "premium", "duration": "monthly"}
)

neonpay.create_payment_stage("premium_monthly", premium_stage)
```

### Payment Callbacks

```python
from neonpay import PaymentResult, PaymentStatus

@neonpay.on_payment
async def handle_payment(result: PaymentResult):
    if result.status == PaymentStatus.COMPLETED:
        # Grant premium access
        user_id = result.user_id
        amount = result.amount
        metadata = result.metadata
        
        print(f"User {user_id} paid {amount} stars")
        print(f"Plan: {metadata.get('plan')}")
        
        # Your business logic here
        await grant_premium_access(user_id, metadata.get('plan'))
```

### Multiple Payment Stages

```python
# Create multiple payment options
stages = {
    "basic": PaymentStage("Basic Plan", "Essential features", 100),
    "premium": PaymentStage("Premium Plan", "All features + support", 300),
    "enterprise": PaymentStage("Enterprise", "Custom solutions", 1000)
}

for stage_id, stage in stages.items():
    neonpay.create_payment_stage(stage_id, stage)

# Send different payments based on user choice
await neonpay.send_payment(user_id, "premium")
```

## 🔧 Configuration

### Error Handling

```python
from neonpay import NeonPayError, PaymentError

try:
    await neonpay.send_payment(user_id, "nonexistent_stage")
except PaymentError as e:
    print(f"Payment error: {e}")
except NeonPayError as e:
    print(f"NEONPAY error: {e}")
```

### Logging

```python
import logging

# Enable NEONPAY logging
logging.getLogger("neonpay").setLevel(logging.INFO)
```

## 📖 Documentation

- **[English Documentation](docs/en/README.md)** - Complete guide in English
- **[Russian Documentation](docs/ru/README.md)** - Полное руководство на русском
- **[Azerbaijani Documentation](docs/az/README.md)** - Azərbaycan dilində tam bələdçi

## 🤝 Examples

Check out the [examples](examples/) directory for complete working examples:

- [Pyrogram Bot Example](examples/pyrogram_example.py)
- [Aiogram Bot Example](examples/aiogram_example.py)
- [python-telegram-bot Example](examples/ptb_example.py)
- [pyTelegramBotAPI Example](examples/telebot_example.py)
- [Raw API Example](examples/raw_api_example.py)

## 🛠️ Requirements

- Python 3.9+
- One of the supported bot libraries:
  - `pyrogram>=2.0.106` for Pyrogram
  - `aiogram>=3.0.0` for Aiogram
  - `python-telegram-bot>=20.0` for python-telegram-bot
  - `pyTelegramBotAPI>=4.0.0` for pyTelegramBotAPI
  - `aiohttp>=3.8.0` for Raw API (optional)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📞 Support

- **Telegram**: [@neonsahib](https://t.me/neonsahib)
- **Issues**: [GitHub Issues](https://github.com/Abbasxan/neonpay/issues)
- **Email**: sultanov.abas@outlook.com

## ⭐ Star History

If you find NEONPAY useful, please consider giving it a star on GitHub!

---

Made with ❤️ by [Abbas Sultanov](https://github.com/Abbasxan)

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/Abbasxan/neonpay",
    "name": "neonpay",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": "Abbas Sultanov <sultanov.abas@outlook.com>",
    "keywords": "telegram, telegram-bot, payment, stars, xtr, crypto, pyrogram, aiogram, python-telegram-bot, telebot, webhook, security, validation, async, payment-processing",
    "author": "Abbas Sultanov",
    "author_email": "Abbas Sultanov <sultanov.abas@outlook.com>",
    "download_url": "https://files.pythonhosted.org/packages/68/ae/d968dc6880408bbf4bcb693a57070bace0b25d3b0d59149300e7cd70abaa/neonpay-2.5.0.tar.gz",
    "platform": null,
    "description": "# NEONPAY - Modern Telegram Stars Payment Library\n\n[![PyPI version](https://badge.fury.io/py/neonpay.svg)](https://badge.fury.io/py/neonpay)\n[![Python Support](https://img.shields.io/pypi/pyversions/neonpay.svg)](https://pypi.org/project/neonpay/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**NEONPAY** is a modern, universal payment processing library for Telegram bots that makes integrating Telegram Stars payments incredibly simple. With support for all major bot libraries and a clean, intuitive API, you can add payments to your bot in just a few lines of code.\n\n## \u2728 Features\n\n- \ud83d\ude80 **Universal Support** - Works with Pyrogram, Aiogram, python-telegram-bot, pyTelegramBotAPI, and raw Bot API\n- \ud83d\udcab **Telegram Stars Integration** - Native support for Telegram's XTR currency\n- \ud83c\udfa8 **Custom Payment Stages** - Create branded payment experiences with custom logos and descriptions\n- \ud83d\udd27 **Simple Setup** - Get started with just 2-3 lines of code\n- \ud83d\udcf1 **Modern Architecture** - Built with async/await and type hints\n- \ud83d\udee1\ufe0f **Error Handling** - Comprehensive error handling and validation\n- \ud83d\udce6 **Zero Dependencies** - Only requires your chosen bot library\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install neonpay\n```\n\n### Basic Usage\n\n```python\nfrom neonpay import create_neonpay, PaymentStage\n\n# Works with any bot library - automatic detection!\nneonpay = create_neonpay(your_bot_instance)\n\n# Create a payment stage\nstage = PaymentStage(\n    title=\"Premium Features\",\n    description=\"Unlock all premium features\",\n    price=100,  # 100 Telegram Stars\n    photo_url=\"https://example.com/logo.png\"\n)\n\n# Add the payment stage\nneonpay.create_payment_stage(\"premium\", stage)\n\n# Send payment to user\nawait neonpay.send_payment(user_id=12345, stage_id=\"premium\")\n\n# Handle successful payments\n@neonpay.on_payment\nasync def handle_payment(result):\n    print(f\"Payment received: {result.amount} stars from user {result.user_id}\")\n```\n\n## \ud83d\udcda Library Support\n\nNEONPAY automatically detects your bot library and creates the appropriate adapter:\n\n### Pyrogram\n\n```python\nfrom pyrogram import Client\nfrom neonpay import create_neonpay\n\napp = Client(\"my_bot\", bot_token=\"YOUR_TOKEN\")\nneonpay = create_neonpay(app)\n```\n\n### Aiogram\n\n```python\nfrom aiogram import Bot, Dispatcher\nfrom neonpay import create_neonpay\n\nbot = Bot(token=\"YOUR_TOKEN\")\ndp = Dispatcher()\nneonpay = create_neonpay(bot, dp)  # Pass dispatcher for aiogram\n```\n\n### python-telegram-bot\n\n```python\nfrom telegram.ext import Application\nfrom neonpay import create_neonpay\n\napplication = Application.builder().token(\"YOUR_TOKEN\").build()\nneonpay = create_neonpay(application)\n```\n\n### pyTelegramBotAPI\n\n```python\nimport telebot\nfrom neonpay import create_neonpay\n\nbot = telebot.TeleBot(\"YOUR_TOKEN\")\nneonpay = create_neonpay(bot)\n```\n\n### Raw Bot API\n\n```python\nfrom neonpay import RawAPIAdapter, NeonPayCore\n\nadapter = RawAPIAdapter(\"YOUR_TOKEN\", webhook_url=\"https://yoursite.com/webhook\")\nneonpay = NeonPayCore(adapter)\n```\n\n## \ud83c\udfaf Advanced Usage\n\n### Custom Payment Stages\n\n```python\nfrom neonpay import PaymentStage\n\n# Create detailed payment stage\npremium_stage = PaymentStage(\n    title=\"Premium Subscription\",\n    description=\"Get access to exclusive features and priority support\",\n    price=500,  # 500 Telegram Stars\n    label=\"Premium Plan\",\n    photo_url=\"https://yoursite.com/premium-logo.png\",\n    payload={\"plan\": \"premium\", \"duration\": \"monthly\"}\n)\n\nneonpay.create_payment_stage(\"premium_monthly\", premium_stage)\n```\n\n### Payment Callbacks\n\n```python\nfrom neonpay import PaymentResult, PaymentStatus\n\n@neonpay.on_payment\nasync def handle_payment(result: PaymentResult):\n    if result.status == PaymentStatus.COMPLETED:\n        # Grant premium access\n        user_id = result.user_id\n        amount = result.amount\n        metadata = result.metadata\n        \n        print(f\"User {user_id} paid {amount} stars\")\n        print(f\"Plan: {metadata.get('plan')}\")\n        \n        # Your business logic here\n        await grant_premium_access(user_id, metadata.get('plan'))\n```\n\n### Multiple Payment Stages\n\n```python\n# Create multiple payment options\nstages = {\n    \"basic\": PaymentStage(\"Basic Plan\", \"Essential features\", 100),\n    \"premium\": PaymentStage(\"Premium Plan\", \"All features + support\", 300),\n    \"enterprise\": PaymentStage(\"Enterprise\", \"Custom solutions\", 1000)\n}\n\nfor stage_id, stage in stages.items():\n    neonpay.create_payment_stage(stage_id, stage)\n\n# Send different payments based on user choice\nawait neonpay.send_payment(user_id, \"premium\")\n```\n\n## \ud83d\udd27 Configuration\n\n### Error Handling\n\n```python\nfrom neonpay import NeonPayError, PaymentError\n\ntry:\n    await neonpay.send_payment(user_id, \"nonexistent_stage\")\nexcept PaymentError as e:\n    print(f\"Payment error: {e}\")\nexcept NeonPayError as e:\n    print(f\"NEONPAY error: {e}\")\n```\n\n### Logging\n\n```python\nimport logging\n\n# Enable NEONPAY logging\nlogging.getLogger(\"neonpay\").setLevel(logging.INFO)\n```\n\n## \ud83d\udcd6 Documentation\n\n- **[English Documentation](docs/en/README.md)** - Complete guide in English\n- **[Russian Documentation](docs/ru/README.md)** - \u041f\u043e\u043b\u043d\u043e\u0435 \u0440\u0443\u043a\u043e\u0432\u043e\u0434\u0441\u0442\u0432\u043e \u043d\u0430 \u0440\u0443\u0441\u0441\u043a\u043e\u043c\n- **[Azerbaijani Documentation](docs/az/README.md)** - Az\u0259rbaycan dilind\u0259 tam b\u0259l\u0259d\u00e7i\n\n## \ud83e\udd1d Examples\n\nCheck out the [examples](examples/) directory for complete working examples:\n\n- [Pyrogram Bot Example](examples/pyrogram_example.py)\n- [Aiogram Bot Example](examples/aiogram_example.py)\n- [python-telegram-bot Example](examples/ptb_example.py)\n- [pyTelegramBotAPI Example](examples/telebot_example.py)\n- [Raw API Example](examples/raw_api_example.py)\n\n## \ud83d\udee0\ufe0f Requirements\n\n- Python 3.9+\n- One of the supported bot libraries:\n  - `pyrogram>=2.0.106` for Pyrogram\n  - `aiogram>=3.0.0` for Aiogram\n  - `python-telegram-bot>=20.0` for python-telegram-bot\n  - `pyTelegramBotAPI>=4.0.0` for pyTelegramBotAPI\n  - `aiohttp>=3.8.0` for Raw API (optional)\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\udcde Support\n\n- **Telegram**: [@neonsahib](https://t.me/neonsahib)\n- **Issues**: [GitHub Issues](https://github.com/Abbasxan/neonpay/issues)\n- **Email**: sultanov.abas@outlook.com\n\n## \u2b50 Star History\n\nIf you find NEONPAY useful, please consider giving it a star on GitHub!\n\n---\n\nMade with \u2764\ufe0f by [Abbas Sultanov](https://github.com/Abbasxan)\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Modern Telegram Stars payment library with multi-bot support and enhanced security",
    "version": "2.5.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/Abbasxan/neonpay/issues",
        "Changelog": "https://github.com/Abbasxan/neonpay/blob/main/CHANGELOG.md",
        "Documentation": "https://github.com/Abbasxan/neonpay#readme",
        "Homepage": "https://github.com/Abbasxan/neonpay",
        "Migration Guide": "https://github.com/Abbasxan/neonpay/blob/main/docs/en/MIGRATION.md",
        "Repository": "https://github.com/Abbasxan/neonpay",
        "Security Policy": "https://github.com/Abbasxan/neonpay/security/policy"
    },
    "split_keywords": [
        "telegram",
        " telegram-bot",
        " payment",
        " stars",
        " xtr",
        " crypto",
        " pyrogram",
        " aiogram",
        " python-telegram-bot",
        " telebot",
        " webhook",
        " security",
        " validation",
        " async",
        " payment-processing"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "025f72af7aabbcee3a4bf72b54172df76985fa3c7fee340a4ca9f26a7c9fd88f",
                "md5": "766f3eb2f0cb15ba8718b89867f2ba2b",
                "sha256": "2d46f4fa735e3774382e498998988fa65d70e8110e0ad94311b80f642e5a7aca"
            },
            "downloads": -1,
            "filename": "neonpay-2.5.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "766f3eb2f0cb15ba8718b89867f2ba2b",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 58907,
            "upload_time": "2025-09-06T15:03:58",
            "upload_time_iso_8601": "2025-09-06T15:03:58.675081Z",
            "url": "https://files.pythonhosted.org/packages/02/5f/72af7aabbcee3a4bf72b54172df76985fa3c7fee340a4ca9f26a7c9fd88f/neonpay-2.5.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "68aed968dc6880408bbf4bcb693a57070bace0b25d3b0d59149300e7cd70abaa",
                "md5": "2114dc3567682ea97880490db41b0250",
                "sha256": "2fe5242931b6c21a36411e92038854a0010686acaf3a77c0d160c643d65de4ec"
            },
            "downloads": -1,
            "filename": "neonpay-2.5.0.tar.gz",
            "has_sig": false,
            "md5_digest": "2114dc3567682ea97880490db41b0250",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 112025,
            "upload_time": "2025-09-06T15:04:00",
            "upload_time_iso_8601": "2025-09-06T15:04:00.330948Z",
            "url": "https://files.pythonhosted.org/packages/68/ae/d968dc6880408bbf4bcb693a57070bace0b25d3b0d59149300e7cd70abaa/neonpay-2.5.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-09-06 15:04:00",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Abbasxan",
    "github_project": "neonpay",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "neonpay"
}