API Documentation

Complete API reference for integrating NEONPAY into your Telegram bots. Learn how to create payment stages, handle transactions, and manage user payments.

API Документация

Полное справочное руководство по API для интеграции NEONPAY в ваших Telegram ботов. Узнайте, как создавать платежные этапы, обрабатывать транзакции и управлять пользовательскими платежами.

API Sənədləşdirməsi

NEONPAY-ı Telegram botlarınıza inteqrasiya etmək üçün tam API arayışı. Ödəniş mərhələlərini necə yaradacağınızı, əməliyyatları işləməyi və istifadəçi ödənişlərini idarə etməyi öyrənin.

Quick Start

Быстрый старт

Sürətli başlanğıc

# Install NEONPAY
pip install neonpay

# Basic setup example
from neonpay import NeonPay
from aiogram import Bot

# Initialize bot and NEONPAY
bot = Bot("YOUR_BOT_TOKEN")
neonpay = NeonPay.create_for_aiogram(bot)

# Create a payment stage
premium_stage = neonpay.create_stage(
    title="Premium Access",
    description="Unlock premium features",
    price=100  # 100 XTR (Telegram Stars)
)

# Handle successful payments
@neonpay.payment_handler(premium_stage)
async def handle_premium_payment(payment_result):
    await payment_result.message.answer("Welcome to Premium! 🎉")
                    

Core Classes

Основные классы

Əsas siniflər

NeonPay

Main class for handling Telegram Stars payments in your bot.

Основной класс для обработки платежей Telegram Stars в вашем боте.

Botunuzda Telegram Stars ödənişlərini idarə etmək üçün əsas sinif.

class NeonPay: def create_for_aiogram(bot: Bot) -> NeonPay def create_for_pyrogram(app: Client) -> NeonPay def create_for_telebot(bot: TeleBot) -> NeonPay def create_for_ptb(app: Application) -> NeonPay

Factory Methods:

Фабричные методы:

Zavod metodları:

create_for_aiogram (bot: Bot) -> NeonPay

Creates NeonPay instance for Aiogram v3 bots

Создает экземпляр NeonPay для ботов Aiogram v3

Aiogram v3 botları üçün NeonPay nümunəsi yaradır

create_for_pyrogram (app: Client) -> NeonPay

Creates NeonPay instance for Pyrogram bots

Создает экземпляр NeonPay для ботов Pyrogram

Pyrogram botları üçün NeonPay nümunəsi yaradır

PaymentStage

Represents a payment configuration that can be reused for multiple transactions.

Представляет конфигурацию платежа, которая может использоваться для нескольких транзакций.

Çoxlu əməliyyatlar üçün istifadə oluna bilən ödəniş konfiqurasiyasını təmsil edir.

def create_stage(
    title: str,
    description: str = None,
    price: int = 100,
    logo_url: str = None
) -> PaymentStage:
    """
    Create a new payment stage configuration
    
    Args:
        title: Payment title shown to user
        description: Optional payment description  
        price: Price in XTR (Telegram Stars)
        logo_url: Optional logo URL for payment
        
    Returns:
        PaymentStage object for handling payments
    """
                        

Payment Methods

Методы платежей

Ödəniş metodları

send_payment()

Send a payment invoice to a user

Отправить счет на оплату пользователю

İstifadəçiyə ödəniş hesabı göndərin

async def send_payment(
    chat_id: int,
    stage: PaymentStage,
    user_id: int = None
) -> Message:
    """
    Send payment invoice to user
    
    Args:
        chat_id: Target chat ID
        stage: Payment stage configuration
        user_id: Optional specific user ID
        
    Returns:
        Sent message object
    """
                        

Usage Example:

Пример использования:

İstifadə nümunəsi:

# Send payment to user
await neonpay.send_payment(
    chat_id=123456789,
    stage=premium_stage
)
                        

payment_handler()

Decorator for handling successful payments

Декоратор для обработки успешных платежей

Uğurlu ödənişləri idarə etmək üçün dekorator

def payment_handler(stage: PaymentStage):
    """
    Decorator for payment success handlers
    
    Args:
        stage: Payment stage to handle
        
    Usage:
        @neonpay.payment_handler(stage)
        async def handle_payment(result):
            # Handle successful payment
            pass
    """

# Example usage
@neonpay.payment_handler(premium_stage)
async def handle_premium(payment_result):
    user_id = payment_result.user_id
    # Grant premium access
    await grant_premium_access(user_id)
    await payment_result.message.answer("Premium activated!")
                        

Error Handling

Обработка ошибок

Xəta idarəetməsi

from neonpay.exceptions import (
    NeonPayError,
    PaymentError, 
    InvalidStageError
)

try:
    await neonpay.send_payment(chat_id, stage)
except PaymentError as e:
    # Handle payment-specific errors
    print(f"Payment failed: {e}")
except InvalidStageError as e:
    # Handle invalid stage configuration
    print(f"Invalid stage: {e}")
except NeonPayError as e:
    # Handle general NEONPAY errors
    print(f"NEONPAY error: {e}")
                    