Урок 3.4 — Ссылки, QR-коды и кнопки оплаты

У каждого инвойса есть три URL-свойства: bot_invoice_url, mini_app_invoice_url и web_app_invoice_url. Все три ведут к оплате одного и того же счёта, но открываются в разных средах. Выбор зависит от того, где находится твой пользователь.

bot_invoice_url — классическая ссылка в бота

Самый распространённый тип. Открывает диалог с @CryptoBot (или @CryptoTestnetBot) и показывает покупателю интерфейс оплаты. Идеально подходит для Telegram-ботов: ты отправляешь эту ссылку пользователю, он нажимает — и сразу видит счёт.

mini_app_invoice_url — ссылка Mini App

Открывает интерфейс оплаты как Telegram Mini App (WebView). Это более современный и быстрый способ: пользователь не покидает твой бот или приложение, оплата происходит во встроенном окне. Используй этот тип, если твой бот уже использует Mini Apps.

web_app_invoice_url — веб-ссылка

Обычная HTTPS-ссылка на сайт pay.crypt.bot. Открывается в любом браузере. Подходит для веб-сайтов, email-писем, рассылок и любых сценариев вне Telegram. Покупатель может оплатить счёт даже без установленного Telegram — через Web-версию.

import asyncio
from aiosend import CryptoPay

async def main():
    cp = CryptoPay(token="YOUR_TOKEN")
    invoice = await cp.create_invoice(amount=10, asset="USDT")

    print("Три способа отправить счёт покупателю:\n")

    print(f"1️⃣ Бот: {invoice.bot_invoice_url}")
    print(f"   → 'Оплатить через @CryptoBot'")
    print(f"    Используй: в Telegram-ботах, кнопки Inline-Keyboard\n")

    print(f"2️⃣ Mini App: {invoice.mini_app_invoice_url}")
    print(f"   → 'Оплатить в Mini App'")
    print(f"    Используй: в WebView, встроенные платежи\n")

    print(f"3️⃣ Web: {invoice.web_app_invoice_url}")
    print(f"   → 'Оплатить на сайте pay.crypt.bot'")
    print(f"    Используй: на веб-сайтах, в email-письмах")

asyncio.run(main())

Объект Invoice имеет свойство qr, которое возвращает прямую ссылку на изображение QR-кода. Это готовый к использованию URL картинки, которую можно отправить пользователю или встроить в веб-страницу.

import asyncio
from aiosend import CryptoPay

async def main():
    cp = CryptoPay(token="YOUR_TOKEN")
    invoice = await cp.create_invoice(amount=10, asset="USDT")

    # Свойство qr — готовая ссылка на изображение QR-кода
    qr_url = invoice.qr
    print(f"QR-код для оплаты: {qr_url}")
    # → https://qr.crypt.bot/?url=https://pay.crypt.bot/invoice/...

    # Также можно получить QR через Network
    qr_via_network = cp.session.network.get_qr(invoice.bot_invoice_url)
    print(f"QR через Network: {qr_via_network}")
    # Результат тот же

asyncio.run(main())

Как работает QR-код внутри? Свойство invoice.qr использует метод Network.get_qr(), который формирует URL вида https://qr.crypt.bot/?url={bot_invoice_url}. Это официальный QR-генератор Crypto Pay.

QR-код для физических точек оплаты

QR-коды особенно полезны в офлайн-сценариях: напечатай QR на чеке, экране терминала или наклейке — покупатель сканирует и оплачивает.

import asyncio
from aiosend import CryptoPay

async def generate_printable_qr(cp: CryptoPay, amount: float, asset: str):
    """Создаёт инвойс и возвращает QR-ссылку для печати."""
    invoice = await cp.create_invoice(
        amount=amount,
        asset=asset,
        description="Оплата на кассе",
        expires_in=3600,  # 1 час на оплату
    )

    result = {
        "id": invoice.invoice_id,
        "amount": invoice.amount,
        "asset": invoice.asset,
        "qr_url": invoice.qr,
        "bot_url": invoice.bot_invoice_url,
        "web_url": invoice.web_app_invoice_url,
        "expires_at": invoice.expires_at,
    }

    print(f"QR для печати: {result['qr_url']}")
    print(f"Сумма: {result['amount']} {result['asset']}")
    print(f"Истекает: {result['expires_at']}")

    return result

async def main():
    cp = CryptoPay(token="YOUR_TOKEN")
    # Для физической точки: сумма фиксированная, срок 1 час
    await generate_printable_qr(cp, 25, "USDT")

asyncio.run(main())

После успешной оплаты в @CryptoBot покупатель видит кнопку. С помощью параметров paid_btn_name и paid_btn_url ты можешь настроить её вид и действие.

Доступные значения paid_btn_name (через enum PaidBtnName):

Пример 1: Кнопка VIEWITEM

Покупатель оплатил и видит кнопку «Посмотреть товар», ведущую на страницу скачивания.

from aiosend import CryptoPay, PaidBtnName

async def viewitem_example():
    cp = CryptoPay(token="YOUR_TOKEN")

    invoice = await cp.create_invoice(
        amount=29.99,
        asset="USDT",
        description="Премиум-шаблон Notion",
        paid_btn_name=PaidBtnName.VIEWITEM,
        paid_btn_url="https://example.com/download/premium-template",
        hidden_message="Ссылка для скачивания: https://example.com/dl/abc123",
    )
    print(f"Счёт: {invoice.amount} {invoice.asset}")
    print(f"Кнопка: VIEWITEM → {invoice.paid_btn_url}")
    return invoice

Пример 2: Кнопка OPENCHANNEL

После оплаты доступа к закрытому Telegram-каналу показываем кнопку «Открыть канал».

from aiosend import CryptoPay, PaidBtnName

async def openchannel_example():
    cp = CryptoPay(token="YOUR_TOKEN")

    invoice = await cp.create_invoice(
        amount=50,
        fiat="USD",
        description="Доступ к закрытому каналу News+",
        paid_btn_name=PaidBtnName.OPENCHANNEL,
        paid_btn_url="https://t.me/private_news_channel",
        payload="channel_access_user_123",
    )
    print(f"Счёт: {invoice.amount} {invoice.fiat}")
    print(f"Кнопка: OPENCHANNEL → {invoice.paid_btn_url}")
    return invoice

Пример 3: Кнопка OPENBOT

После оплаты возвращаем пользователя обратно в твоего бота с параметром start.

from aiosend import CryptoPay, PaidBtnName

async def openbot_example():
    cp = CryptoPay(token="YOUR_TOKEN")

    invoice = await cp.create_invoice(
        amount=15,
        asset="TON",
        description="Билет на вебинар",
        paid_btn_name=PaidBtnName.OPENBOT,
        paid_btn_url="https://t.me/your_bot?start=webinar_2024",
        allow_anonymous=False,
        payload="webinar_ticket_user_456",
    )
    print(f"Счёт: {invoice.amount} {invoice.asset}")
    print(f"Кнопка: OPENBOT → {invoice.paid_btn_url}")
    return invoice

Пример 4: Кнопка CALLBACK

После оплаты отправляем POST-запрос на твой сервер для кастомной обработки.

from aiosend import CryptoPay, PaidBtnName

async def callback_example():
    cp = CryptoPay(token="YOUR_TOKEN")

    invoice = await cp.create_invoice(
        amount=99,
        asset="USDT",
        description="Годовая подписка",
        paid_btn_name=PaidBtnName.CALLBACK,
        paid_btn_url="https://api.example.com/payment/callback",
        payload='{"user_id":789,"plan":"annual"}',
    )
    print(f"Счёт: {invoice.amount} {invoice.asset}")
    print(f"Кнопка: CALLBACK → {invoice.paid_btn_url}")
    # При нажатии на кнопку Crypto Pay отправит POST с данными инвойса
    # на указанный URL. Твой сервер должен обработать этот запрос.
    return invoice

Два логических параметра управляют поведением платёжного интерфейса. Они влияют на то, что видит и может делать покупатель во время оплаты.

import asyncio
from aiosend import CryptoPay

async def main():
    cp = CryptoPay(token="YOUR_TOKEN")

    # Счёт с обязательной авторизацией и комментариями
    invoice1 = await cp.create_invoice(
        amount=10,
        asset="USDT",
        allow_comments=True,
        allow_anonymous=False,
        description="Оплата с идентификацией",
    )
    print(f"Счёт #{invoice1.invoice_id}: анонимность=OFF, комментарии=ON")

    # Быстрая оплата без лишних полей
    invoice2 = await cp.create_invoice(
        amount=5,
        asset="TON",
        allow_comments=False,
        allow_anonymous=True,
        description="Быстрая оплата",
    )
    print(f"Счёт #{invoice2.invoice_id}: анонимность=ON, комментарии=OFF")

asyncio.run(main())

hidden_message — это текст, который покупатель видит только после успешной оплаты. До оплаты сообщение скрыто. Это идеальный механизм для доставки цифровых товаров: ссылок на скачивание, промокодов, инструкций, кодов активации.

import asyncio
import secrets
from aiosend import CryptoPay, PaidBtnName

async def main():
    cp = CryptoPay(token="YOUR_TOKEN")

    # Генерируем уникальный код активации
    activation_code = secrets.token_hex(8).upper()

    invoice = await cp.create_invoice(
        amount=19.99,
        asset="USDT",
        description="Активация Premium на 1 месяц",

        # Покупатель увидит это сообщение ПОСЛЕ оплаты
        hidden_message=(
            "✅ Оплата прошла успешно!\n\n"
            f"Ваш код активации:\n{activation_code}\n\n"
            "Как активировать:\n"
            "1. Откройте бота: @your_bot\n"
            "2. Отправьте команду /activate\n"
            "3. Введите код выше\n\n"
            "Ссылка: https://t.me/your_bot"
        ),

        # Кнопка после оплаты
        paid_btn_name=PaidBtnName.OPENBOT,
        paid_btn_url="https://t.me/your_bot?start=activated",

        # Внутренние данные
        payload=activation_code,
    )

    print(f"Счёт #{invoice.invoice_id}")
    print(f"Код активации (в payload): {activation_code}")
    print(f"Ссылка: {invoice.bot_invoice_url}")

asyncio.run(main())

Соберём всё вместе: ссылки всех типов, QR-код, кастомная кнопка после оплаты, скрытое сообщение, управление комментариями и анонимностью.

import asyncio
import json
import secrets
from aiosend import CryptoPay, PaidBtnName

class DigitalGoodsStore:
    """Магазин цифровых товаров с оплатой через Crypto Pay."""

    def __init__(self, token: str):
        self.cp = CryptoPay(token=token)

    async def sell_product(
        self,
        product_name: str,
        price: float,
        asset: str,
        download_link: str,
    ) -> dict:
        """
        Продаёт цифровой товар.
        Возвращает словарь со всеми ссылками и QR.
        """
        # Генерируем уникальный код заказа
        order_id = secrets.token_hex(6)

        invoice = await self.cp.create_invoice(
            amount=price,
            asset=asset,
            description=f"Купить: {product_name}",
            hidden_message=(
                f"🎉 Спасибо за покупку!\n\n"
                f"Товар: {product_name}\n"
                f"Заказ: #{order_id}\n\n"
                f"Ссылка для скачивания:\n{download_link}\n\n"
                f"Срок действия ссылки: 48 часов"
            ),
            paid_btn_name=PaidBtnName.VIEWITEM,
            paid_btn_url=download_link,
            payload=json.dumps({
                "order_id": order_id,
                "product": product_name,
                "price": price,
            }),
            allow_comments=False,
            allow_anonymous=False,  # требуется регистрация
        )

        return {
            "order_id": order_id,
            "invoice_id": invoice.invoice_id,
            "amount": invoice.amount,
            "asset": invoice.asset,
            "status": invoice.status,

            # Все три типа ссылок
            "bot_url": invoice.bot_invoice_url,
            "mini_app_url": invoice.mini_app_invoice_url,
            "web_url": invoice.web_app_invoice_url,

            # QR-код
            "qr_url": invoice.qr,

            # Кнопка после оплаты
            "paid_btn": invoice.paid_btn_name,
            "paid_btn_url": invoice.paid_btn_url,
        }

    async def present_invoice(self, invoice_data: dict):
        """Выводит красивое представление всех ссылок."""
        print(f"\n{'='*50}")
        print(f"   Заказ #{invoice_data['order_id']}")
        print(f"   Сумма: {invoice_data['amount']} {invoice_data['asset']}")
        print(f"{'='*50}")
        print(f"🔗 Ссылка в боте:       {invoice_data['bot_url']}")
        print(f"🔗 Ссылка Mini App:     {invoice_data['mini_app_url']}")
        print(f"🔗 Ссылка Web:         {invoice_data['web_url']}")
        print(f"📱 QR-код:              {invoice_data['qr_url']}")
        print(f"🔘 Кнопка:              {invoice_data['paid_btn']}")
        print(f"📎 URL кнопки:          {invoice_data['paid_btn_url']}")
        print(f"{'='*50}\n")

async def main():
    store = DigitalGoodsStore("YOUR_TOKEN")

    # Продаём первый товар
    result1 = await store.sell_product(
        product_name="Notion Template Pro",
        price=29.99,
        asset="USDT",
        download_link="https://example.com/dl/template-pro",
    )
    await store.present_invoice(result1)

    # Продаём второй товар
    result2 = await store.sell_product(
        product_name="Видеокурс Python Advanced",
        price=49.00,
        asset="USDT",
        download_link="https://example.com/dl/python-advanced",
    )
    await store.present_invoice(result2)

asyncio.run(main())

При работе с тестовой сетью все три типа ссылок ведут на тестовые ресурсы. Это важно помнить, чтобы не перепутать окружения.

import asyncio
from aiosend import CryptoPay, TESTNET

def detect_network_from_url(url: str) -> str:
    """Определяет сеть по ссылке на инвойс."""
    if "testnet" in url.lower():
        return "TESTNET"
    return "MAINNET"

async def main():
    # Создаём инвойс в TESTNET
    cp = CryptoPay(token="YOUR_TEST_TOKEN", network=TESTNET)
    invoice = await cp.create_invoice(amount=5, asset="USDT")

    print(f"bot URL: {invoice.bot_invoice_url}")
    print(f"Сеть: {detect_network_from_url(invoice.bot_invoice_url)}")
    # → TESTNET

    # Проверяем, что ссылка ведёт в правильного бота
    if "@CryptoTestnetBot" in invoice.bot_invoice_url:
        print("✅ Это тестовая ссылка")
    elif "@CryptoBot" in invoice.bot_invoice_url:
        print("✅ Это основная ссылка")

asyncio.run(main())

Для быстрого доступа — все URL-свойства объекта Invoice в одной таблице: