Урок 3.1 — Создание инвойсов

Invoice (счёт) — это ключевой объект в Crypto Pay API. Через него ты просишь пользователя оплатить определённую сумму в определённой валюте. Crypto Pay создаёт платёжную ссылку, кнопку или QR-код, по которым покупатель переходит в @CryptoBot и совершает оплату.

Инвойс проходит через три статуса:

Статусы меняются автоматически: при создании инвойс получает статус ACTIVE. Когда покупатель оплачивает — статус меняется на PAID. Если оплата не поступила в течение заданного времени — статус становится EXPIRED.

Метод create_invoice() — основной инструмент для создания счетов. Доступен как у экземпляра CryptoPay, так и у Network. Разберём каждый параметр подробно.

async def create_invoice(
    self,
    amount: float | str,
    asset: str | None = None,
    fiat: str | None = None,
    accepted_assets: list[str] | None = None,
    currency_type: str | None = None,
    swap_to: str | None = None,
    description: str | None = None,
    hidden_message: str | None = None,
    paid_btn_name: str | None = None,
    paid_btn_url: str | None = None,
    payload: str | None = None,
    allow_comments: bool = True,
    allow_anonymous: bool = True,
    expires_in: int | None = None,
) -> Invoice

Все параметры, кроме amount, являются опциональными. Однако asset или fiat должны быть указаны (иначе API вернёт ошибку).

* — asset или fiat должны быть указаны. Если указан asset, счёт создаётся в криптовалюте. Если указан fiat — в фиатной валюте, и покупатель оплачивает эквивалент в криптовалюте по текущему курсу.

При создании инвойса нужно указать, в какой валюте принимается платёж. У aiosend есть три взаимосвязанных параметра для настройки валюты: asset, fiat и currency_type.

Параметр asset

Указывает криптовалюту, в которой создаётся счёт. Допустимые значения:

Параметр fiat

Указывает фиатную валюту для счёта. Сумма указывается в фиате, а покупатель оплачивает эквивалент в криптовалюте по текущему курсу Crypto Pay. Допустимые значения:

Параметр currency_type

Определяет, какой тип валюты используется. Два значения:

Важно! Если ты указываешь asset, то currency_type автоматически устанавливается в "crypto". Если указываешь fiat — в "fiat". Явно передавать currency_type нужно только в особых случаях (например, при создании fiat-счёта с accepted_assets).

# Счёт в криптовалюте (USDT)
invoice = await cp.create_invoice(amount=100, asset="USDT")

# Счёт в фиате (USD)
invoice = await cp.create_invoice(amount=50, fiat="USD")

# Счёт в криптовалюте с явным currency_type
invoice = await cp.create_invoice(
    amount=0.5,
    asset="TON",
    currency_type="crypto",
)

# Счёт в фиате с явным currency_type
invoice = await cp.create_invoice(
    amount=100,
    fiat="EUR",
    currency_type="fiat",
)

Параметр accepted_assets позволяет указать список криптовалют, которыми покупатель может оплатить счёт. Это особенно полезно для fiat-инвойсов: ты указываешь сумму в долларах, а покупатель может оплатить USDT, TON, BTC или любой другой актив из списка.

Если accepted_assets не указан, то для fiat-счёта покупатель может оплатить любым активом, который поддерживает Crypto Pay. Если указан — только активами из списка.

# Счёт на 100 USD, оплатить можно только USDT или TON
invoice = await cp.create_invoice(
    amount=100,
    fiat="USD",
    accepted_assets=["USDT", "TON"],
)

# Счёт на 50 EUR, оплатить можно TON, BTC или ETH
invoice = await cp.create_invoice(
    amount=50,
    fiat="EUR",
    accepted_assets=["TON", "BTC", "ETH"],
)

Параметр swap_to включает автоматическую конвертацию полученных средств в другой актив. Это мощная функция: ты можешь принять оплату в USDT, а на баланс получить TON (или любой другой поддерживаемый актив).

Варианты использования:

• Принимать всё в USDT, но хранить в TON (меньше комиссий за вывод)
• Принимать в любой криптовалюте, но конвертировать в стейблкоин
• Автоматически обменивать полученные средства в SEND или JET для дальнейших операций

# Принимаем USDT, на баланс получаем TON
invoice = await cp.create_invoice(
    amount=100,
    asset="USDT",
    swap_to="TON",
)

# Принимаем в фиате, конвертируем в USDC
invoice = await cp.create_invoice(
    amount=50,
    fiat="USD",
    swap_to="USDC",
)

# Принимаем BTC, конвертируем в USDT
invoice = await cp.create_invoice(
    amount=0.001,
    asset="BTC",
    swap_to="USDT",
)

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

invoice = await cp.create_invoice(
    amount=10,
    asset="USDT",
    description="Премиум-подписка на 1 месяц",
    hidden_message=(
        "Благодарим за покупку!\n"
        "Ваш промокод: PREMIUM-12345\n"
        "Активируйте по ссылке: https://example.com/activate"
    ),
)

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

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

from aiosend import PaidBtnName

# Кнопка "Посмотреть товар"
invoice = await cp.create_invoice(
    amount=25,
    asset="USDT",
    paid_btn_name=PaidBtnName.VIEWITEM,
    paid_btn_url="https://example.com/download/item123",
)

# Кнопка "Открыть канал" — для продажи доступа к каналу
invoice = await cp.create_invoice(
    amount=50,
    fiat="USD",
    paid_btn_name=PaidBtnName.OPENCHANNEL,
    paid_btn_url="https://t.me/private_channel",
)

# Кнопка с callback — для кастомной обработки
invoice = await cp.create_invoice(
    amount=15,
    asset="TON",
    paid_btn_name=PaidBtnName.CALLBACK,
    paid_btn_url="https://api.example.com/payment/callback",
)

payload — это строка до 4096 символов, которая хранит произвольные данные, связанные со счётом. Покупатель не видит payload — это внутренний механизм для твоей логики.

Типичные сценарии использования:

• ID товара: payload="product_123" — при обработке оплаты ты знаешь, какой товар купил пользователь
• ID пользователя: payload="user_45678" — знаешь, кто оплатил
• JSON-данные: payload='{"user_id":456,"item":"premium"}' — структурированные данные (можно использовать PayloadData)
• ID заказа: payload="order_98765" — для связки с твоей CRM

import json

# Простой payload
invoice = await cp.create_invoice(
    amount=10,
    asset="USDT",
    payload="user_12345_product_premium",
)

# Структурированный JSON payload
payload_data = {
    "user_id": 12345,
    "product_id": "premium_month",
    "quantity": 1,
    "coupon": "SAVE10",
}
invoice = await cp.create_invoice(
    amount=20,
    fiat="USD",
    payload=json.dumps(payload_data),
)

Эти два логических параметра управляют поведением платёжного интерфейса в @CryptoBot.

# Быстрая оплата без комментариев, но с идентификацией
invoice = await cp.create_invoice(
    amount=5,
    asset="USDT",
    allow_comments=False,
    allow_anonymous=False,
)

# Полная свобода: комментарии и анонимность разрешены
invoice = await cp.create_invoice(
    amount=100,
    fiat="RUB",
    allow_comments=True,
    allow_anonymous=True,
)

Параметр expires_in задаёт время в секундах, через которое неоплаченный счёт автоматически перейдёт в статус EXPIRED.

# Счёт на 5 минут
invoice = await cp.create_invoice(
    amount=0.5,
    asset="TON",
    expires_in=300,
)

# Счёт на 24 часа
invoice = await cp.create_invoice(
    amount=100,
    fiat="USD",
    expires_in=86400,
)

# Без expires_in — используется стандартный срок Crypto Pay
# (обычно 2 часа, но может меняться)
invoice = await cp.create_invoice(
    amount=10,
    asset="USDT",
    # expires_in не указан → срок по умолчанию
)

Метод create_invoice() возвращает объект Invoice (Pydantic-модель). Вот все его поля:

Как видишь, объект Invoice содержит не только те данные, которые ты передал при создании, но и множество служебных полей: ссылки всех типов, курсы, даты и информацию об оплате.

invoice = await cp.create_invoice(amount=100, asset="USDT")

print(f"ID: {invoice.invoice_id}")
print(f"Сумма: {invoice.amount} {invoice.asset}")
print(f"Статус: {invoice.status}")
print(f"Создан: {invoice.created_at}")
print(f"Ссылка в боте: {invoice.bot_invoice_url}")
print(f"Ссылка Mini App: {invoice.mini_app_invoice_url}")
print(f"Ссылка Web App: {invoice.web_app_invoice_url}")

# После оплаты будут доступны:
# print(f"Оплачено: {invoice.paid_amount} {invoice.paid_asset}")
# print(f"Курс: {invoice.paid_usd_rate}")
# print(f"Оплачено в: {invoice.paid_at}")

Давай рассмотрим несколько реальных сценариев создания инвойсов от простых к сложным.

Пример 1: Простой крипто-счёт

Самый базовый случай: счёт на 50 USDT без дополнительных опций.

import asyncio
from aiosend import CryptoPay

async def main():
    cp = CryptoPay(token="YOUR_TOKEN")
    invoice = await cp.create_invoice(amount=50, asset="USDT")
    print(f"Счёт #{invoice.invoice_id} создан!")
    print(f"Ссылка: {invoice.bot_invoice_url}")
    print(f"Статус: {invoice.status}")

asyncio.run(main())

Пример 2: Fiat-счёт с выбором валют

Счёт на 100 рублей с возможностью оплаты USDT или TON.

async def create_fiat_invoice():
    cp = CryptoPay(token="YOUR_TOKEN")
    invoice = await cp.create_invoice(
        amount=100,
        fiat="RUB",
        accepted_assets=["USDT", "TON"],
        description="Оплата заказа №123",
    )
    print(f"Счёт на {invoice.amount} {invoice.fiat}")
    print(f"Принимаем: {invoice.accepted_assets}")
    print(f"Ссылка: {invoice.bot_invoice_url}")
    return invoice

Пример 3: Счёт со swap

Принимаем USDT, на баланс получаем TON.

async def create_swap_invoice():
    cp = CryptoPay(token="YOUR_TOKEN")
    invoice = await cp.create_invoice(
        amount=50,
        asset="USDT",
        swap_to="TON",
        description="Автоматическая конвертация в TON",
    )
    print(f"Счёт: {invoice.amount} {invoice.asset}")
    print(f"После оплаты будет конвертировано в: {invoice.swap_to}")
    return invoice

Пример 4: Счёт с кастомной кнопкой

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

from aiosend import PaidBtnName

async def create_invoice_with_button():
    cp = CryptoPay(token="YOUR_TOKEN")
    invoice = await cp.create_invoice(
        amount=15,
        asset="USDT",
        description="Премиум-доступ на 1 месяц",
        paid_btn_name=PaidBtnName.OPENBOT,
        paid_btn_url="https://t.me/your_bot?start=premium_123",
        payload="premium_activation_user_123",
    )
    print(f"Счёт: {invoice.amount} {invoice.asset}")
    print(f"Кнопка: {invoice.paid_btn_name}")
    return invoice

Пример 5: Полный счёт со всеми параметрами

Максимальная конфигурация с большинством параметров.

async def create_full_invoice():
    cp = CryptoPay(token="YOUR_TOKEN")
    invoice = await cp.create_invoice(
        amount=99.99,
        fiat="USD",
        accepted_assets=["USDT", "TON", "BTC"],
        description="Подписка Premium на 1 год",
        hidden_message=(
            "Спасибо за покупку Premium!\n"
            "Код активации: PRM-2024-X9K2\n"
            "Ссылка: https://example.com/activate"
        ),
        paid_btn_name=PaidBtnName.VIEWITEM,
        paid_btn_url="https://example.com/dashboard",
        payload='{"user_id": 123, "plan": "premium_annual"}',
        allow_comments=False,
        allow_anonymous=False,
        expires_in=86400,
    )
    return invoice

Пример 6: Обработка ошибок при создании

Всегда обрабатывай возможные исключения.

from aiosend import CryptoPay
from aiosend.exceptions import APIError, MethodValuesError

async def create_invoice_safe():
    cp = CryptoPay(token="YOUR_TOKEN")
    try:
        invoice = await cp.create_invoice(
            amount=100,
            asset="USDT",
            expires_in=3600,
        )
        return invoice
    except MethodValuesError as e:
        print(f"Ошибка в параметрах: {e}")
    except APIError as e:
        print(f"Ошибка API: {e}")
    except Exception as e:
        print(f"Неожиданная ошибка: {e}")
    return None

Если ты работаешь в синхронном окружении (например, в простом скрипте или Flask-приложении), используй SyncCryptoPay:

from aiosend import SyncCryptoPay

cp = SyncCryptoPay(token="YOUR_TOKEN")
invoice = cp.create_invoice(amount=50, asset="USDT")
print(f"Счёт #{invoice.invoice_id}: {invoice.bot_invoice_url}")

# Все параметры те же, что и в асинхронной версии
invoice = cp.create_invoice(
    amount=100,
    fiat="USD",
    accepted_assets=["USDT", "TON"],
    description="Синхронный счёт",
)

В aiosend можно работать напрямую с классом Network, минуя CryptoPay. Это полезно, если ты используешь кастомную сессию или хочешь отправить запрос напрямую.

from aiosend import CryptoPay
from aiosend.network import Network

# Network доступен через cp.network
cp = CryptoPay(token="YOUR_TOKEN")
invoice = await cp.network.create_invoice(amount=0.1, asset="TON")

# Или напрямую
network = Network(token="YOUR_TOKEN")
invoice = await network.create_invoice(amount=25, asset="USDT")