Оплата звёздами

Платежи в StaticGram работают только во внутренней валюте звёзд: currency = XTR. Платёжные провайдеры (provider_token) и фиатные валюты не поддерживаются.

Схема оплаты

1. Бот выставляет счёт: sendInvoice в чат или createInvoiceLink для ссылки.
2. Пользователь нажимает «Оплатить», бот получает обновление pre_checkout_query.
3. Бот в течение 10 секунд отвечает answerPreCheckoutQuery с ok: true (или с ошибкой, чтобы отменить оплату).
4. Звёзды списываются, в чат приходит сообщение с полем successful_payment. Сохраните telegram_payment_charge_id: он нужен для возврата.

Выставление счёта

curl "https://api.staticgram.top/bot$TOKEN/sendInvoice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "title": "Премиум-доступ",
    "description": "30 дней без ограничений",
    "payload": "premium-30d-user-123",
    "currency": "XTR",
    "prices": [{"label": "Премиум", "amount": 100}]
  }'

provider_token передавать не нужно (пустая строка допустима). Для XTR в prices должна быть ровно одна позиция. Можно передать свою клавиатуру, но первой кнопкой должна быть кнопка оплаты (pay: true).

Обработка на aiogram 3

from aiogram import F
from aiogram.types import LabeledPrice, Message, PreCheckoutQuery


@dp.message(F.text == "/buy")
async def buy(message: Message):
    await message.answer_invoice(
        title="Премиум-доступ",
        description="30 дней без ограничений",
        payload="premium-30d",
        currency="XTR",
        prices=[LabeledPrice(label="Премиум", amount=100)],
    )


@dp.pre_checkout_query()
async def pre_checkout(query: PreCheckoutQuery):
    await query.answer(ok=True)


@dp.message(F.successful_payment)
async def paid(message: Message):
    charge_id = message.successful_payment.telegram_payment_charge_id
    await message.answer(f"Оплата получена: {charge_id}")

Возвраты, баланс, подписки

• refundStarPayment возвращает звёзды пользователю; в чат приходит сервисное сообщение refunded_payment.
• getMyStarBalance и getStarTransactions показывают баланс и историю операций бота.
• Подписки: createInvoiceLink с subscription_period = 2592000 (30 дней) продлевается автоматически; управлять ей можно через editUserStarSubscription.
• Платный контент: sendPaidMedia работает в личных чатах. Платные медиа в каналах и группах не поддерживаются.
• Подарки: getAvailableGifts, sendGift (оплачиваются с баланса бота).