Оплата статиками
Платежи в StaticGram работают во внутренних валютах: статики (currency = XTR) и коины (см. Счета в коинах). Платёжные провайдеры (provider_token) и фиатные валюты не поддерживаются.
Схема оплаты
- Бот выставляет счёт:
sendInvoiceв чат илиcreateInvoiceLinkдля ссылки. - Пользователь нажимает «Оплатить», бот получает обновление
pre_checkout_query. - Бот в течение 10 секунд отвечает
answerPreCheckoutQueryсok: true(или с ошибкой, чтобы отменить оплату). - Статики списываются, в чат приходит сообщение с полем
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}")Лимиты счетов
| Значение | |
|---|---|
| Валюта | XTR (статики) или коины (TON/GRAM, удобнее — sendGramInvoice); другая валюта или непустой provider_token → 400 PAYMENT_PROVIDER_INVALID |
| Сумма счёта в коинах | от 0.01 до 10 000 коинов, не больше 9 знаков после запятой; без подписок |
Сумма счёта (sendInvoice, createInvoiceLink) | от 1 до 100 000 статиков (сумма всех prices); иначе 400 CURRENCY_TOTAL_AMOUNT_INVALID |
Подписка (createInvoiceLink с subscription_period) | период ровно 2592000 (30 дней), цена от 1 до 10 000 статиков |
Платная подписка на канал (createChatSubscriptionInviteLink) | период 2592000, цена 1-10 000 статиков |
Платные медиа (sendPaidMedia) | star_count от 1 до 25 000 |
title / description / payload | 1-32 символа / 1-255 символов / 1-128 байт |
Ответ на pre_checkout_query | 10 секунд |
Возвраты, баланс, подписки
refundStarPaymentвозвращает статики пользователю поtelegram_payment_charge_id; в чат приходит сервисное сообщениеrefunded_payment. Повторный возврат:CHARGE_ALREADY_REFUNDED, не хватает статиков на балансе бота:BALANCE_TOO_LOW.getMyStarBalanceиgetStarTransactionsпоказывают баланс и историю операций бота.- Подписки:
createInvoiceLinkсsubscription_period= 2592000 продлевается автоматически; управлять ей можно черезeditUserStarSubscription. - Платный контент:
sendPaidMediaработает в личных чатах, каналах, супергруппах и бизнес-чатах. - Платные подписки на канал:
createChatSubscriptionInviteLink(только каналы), статики поступают на баланс канала. - Оплата из Mini App:
createInvoiceLink+Telegram.WebApp.openInvoice, см. Mini Apps.
Счета в коинах
Коины — внутренняя валюта StaticGram (в API обозначается TON/GRAM, баланс TON пользователя). Методов sendGramInvoice и createGramInvoiceLink нет в официальном Bot API, библиотеки их не знают: вызывайте обычным HTTP-запросом или опишите метод в aiogram, как в примере ниже.
sendGramInvoice отправляет счёт в чат, createGramInvoiceLink возвращает ссылку на счёт (например, для Telegram.WebApp.openInvoice). Параметры — как у sendInvoice / createInvoiceLink, но без currency, prices и provider_token: цена передаётся одним полем в коинах.
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
amount | String или Float | один из двух | Цена в коинах: "1.5", "0,01", 2.5. Точка или запятая, не больше 9 знаков после запятой. Для дробных сумм надёжнее строка. |
nanoton_amount | Integer | один из двух | Цена в нанотонах: 1 коин = 1 000 000 000. |
label | String | нет | Подпись позиции, до 64 символов. По умолчанию — title. |
chat_id, title, description, payload, photo_url, photo_size, photo_width, photo_height, start_parameter, message_thread_id, disable_notification, protect_content, reply_parameters, reply_markup | Как у sendInvoice (chat_id, message_thread_id, reply_* — только для sendGramInvoice). Своя клавиатура — с кнопкой pay: true первой. | ||
Сумма — от 0.01 до 10 000 коинов, как у обычных счетов в коинах. Подписки в коинах не поддерживаются.
curl "https://api.staticgram.top/bot$TOKEN/sendGramInvoice" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"title": "Премиум-доступ",
"description": "30 дней без ограничений",
"payload": "premium-30d-user-123",
"amount": "1.5"
}'
curl "https://api.staticgram.top/bot$TOKEN/createGramInvoiceLink" \
-H "Content-Type: application/json" \
-d '{"title": "Пополнение", "description": "Игровой счёт", "payload": "topup-123", "amount": "0,01"}'aiogram 3: опишите метод как TelegramMethod и вызывайте через bot(...). Обработчики pre_checkout_query и successful_payment — те же, что для статиков.
from aiogram import Bot, F
from aiogram.methods.base import TelegramMethod
from aiogram.types import InlineKeyboardMarkup, Message, PreCheckoutQuery
class SendGramInvoice(TelegramMethod[Message]):
__returning__ = Message
__api_method__ = "sendGramInvoice"
chat_id: int | str
title: str
description: str
payload: str
amount: str | float | None = None
nanoton_amount: int | None = None
label: str | None = None
reply_markup: InlineKeyboardMarkup | None = None
class CreateGramInvoiceLink(TelegramMethod[str]):
__returning__ = str
__api_method__ = "createGramInvoiceLink"
title: str
description: str
payload: str
amount: str | float | None = None
nanoton_amount: int | None = None
label: str | None = None
@router.message(F.text == "/buy")
async def buy(message: Message, bot: Bot):
await bot(SendGramInvoice(chat_id=message.chat.id, title="Премиум-доступ",
description="30 дней без ограничений",
payload=f"premium-{message.from_user.id}", amount="1.5"))
link = await bot(CreateGramInvoiceLink(title="Пополнение", description="Игровой счёт",
payload="topup", amount="0,01"))
@router.pre_checkout_query()
async def pre_checkout(query: PreCheckoutQuery):
await query.answer(ok=True) # query.currency == "TON", query.total_amount в нанотонах
@router.message(F.successful_payment)
async def paid(message: Message):
sp = message.successful_payment
gram = sp.model_extra.get("gram_amount") # "1.5" — поле StaticGram
charge_id = sp.telegram_payment_charge_id # для refundGramPaymentОплата идёт с баланса коинов пользователя на баланс коинов бота. Обновления — как у обычного счёта в коинах: в invoice, pre_checkout_query, successful_payment и refunded_payment приходят currency = "TON", total_amount в нанотонах и дополнительное поле StaticGram gram_amount — сумма в коинах строкой:
"successful_payment": {
"currency": "TON",
"total_amount": 1500000000,
"gram_amount": "1.5",
"invoice_payload": "premium-30d-user-123",
"telegram_payment_charge_id": "stx...",
"provider_payment_charge_id": "..."
}Ошибки (400): AMOUNT_INVALID (нет цены, переданы обе, не число или больше 9 знаков после запятой), AMOUNT_TOO_SMALL (меньше 0.01 коина), AMOUNT_TOO_LARGE (больше 10 000 коинов), CURRENCY_INVALID (передан currency, отличный от GRAM/TON), PRICES_INVALID (передан prices или label длиннее 64 символов), PAYMENT_PROVIDER_INVALID (передан provider_token), а также ошибки sendInvoice (INVOICE_TITLE_INVALID и т. п.). Текст ошибки объясняет, что не так, например Bad Request: AMOUNT_TOO_SMALL: the minimum GRAM invoice is 0.01 GRAM (10000000 nanoton), got 0.001 GRAM.
Деньги бота в коинах: getMyGramBalance — баланс (nanoton_amount и gram_amount), refundGramPayment (user_id, telegram_payment_charge_id) — возврат платежа, withdrawGramBalance (user_id, nanoton_amount, request_id — все необязательные) — вывод владельцу или пользователю. Синонимы: getMyTonBalance, refundTonPayment, withdrawTonBalance. Поле gram_amount описано в типах Invoice, PreCheckoutQuery, SuccessfulPayment и RefundedPayment.
Вывод статиков владельцу бота
Метода withdrawStarBalance нет в официальном Bot API Telegram. Библиотеки (aiogram, python-telegram-bot и др.) его не знают — вызывайте его обычным HTTP-запросом, как в примере ниже.
Статики, которые бот заработал (счета XTR, платный контент, подписки), владелец бота может вывести на свой аккаунт двумя способами:
- в @BotFather: команда
/bank(или кнопка «⭐ Звёзды» в карточке бота из/mybots) → выбор бота → «Вывести» → сумма или «Вывести всё» → подтверждение. Там же кнопка «Возврат платежа»: пришлитеtelegram_payment_charge_id, подтвердите — и статики вернутся покупателю, как приrefundStarPayment; - самим ботом — методом
withdrawStarBalance.
Владелец получает статики нативно: от официального аккаунта StaticGram (777000) приходит сервисное сообщение о подарке статиков и текст «Вывод с бота @имя_бота в размере X ⭐️ успешно оформлен!». В истории статиков владельца появляется запись «Вывод с бота», у бота — списание «Вывод владельцу» (в getStarTransactions это транзакция с receiver.type = other).
Выводится весь баланс бота: стартовые статики ботам не начисляются, поэтому на балансе только то, что бот заработал. Минимальная сумма вывода задаётся сервером (по умолчанию 1 статик), как и лимит частоты: не больше N выводов одного бота в минуту (по умолчанию 10; повтор с тем же request_id не считается).
Вывод другому пользователю
Методом withdrawStarBalance бот может отправить статики не владельцу, а любому пользователю — передайте user_id. Получатель должен существовать, не быть удалённым, ботом, системным аккаунтом (777000 и т. п.) или замороженным. Все остальные правила те же: минимум, лимит частоты, запрет вывода администрацией, идемпотентность по request_id (тот же ключ с другим получателем — REQUEST_ID_CONFLICT).
Получатель видит сервисное сообщение о подарке статиков от 777000 и текст «Вывод от бота @имя_бота в размере X ⭐️ зачислен на ваш баланс.», в его истории статиков — запись «Вывод от бота» с именем бота. У бота в истории — «Вывод пользователю» с @username (или id) получателя. Владелец бота получает от 777000 уведомление «Вывод с бота @имя_бота в размере X ⭐️ пользователю @получатель успешно оформлен!». Как и вывод владельцу, такой вывод не влияет на рейтинг аккаунта получателя.
withdrawStarBalance
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
user_id | Integer или String | нет | Получатель: id пользователя или @username. Не указан (или указан id владельца) — статики получает владелец бота. |
star_count | Integer | нет | Сколько статиков вывести. Не указан — выводится всё, что доступно. |
request_id | String | нет | Ключ идемпотентности, 1–40 печатных ASCII-символов. Повторный вызов с тем же ключом вернёт первый результат и ничего не спишет; тот же ключ с другим star_count или user_id — ошибка REQUEST_ID_CONFLICT. |
Возвращает StarTransaction списания с бота и дополнительные поля StaticGram: star_count (сколько выведено), remaining_balance (остаток бота), owner_user_id, recipient_user_id (кто получил статики; при выводе владельцу совпадает с owner_user_id).
curl "https://api.staticgram.top/bot$TOKEN/withdrawStarBalance" \
-H "Content-Type: application/json" \
-d '{"star_count": 500, "request_id": "payout-2026-10-01"}'{"ok": true, "result": {"id": "1841", "amount": 500, "date": 1790000000,
"receiver": {"type": "other"}, "star_count": 500, "remaining_balance": 1250,
"owner_user_id": 1000123, "recipient_user_id": 1000123}}Вывод другому пользователю:
curl "https://api.staticgram.top/bot$TOKEN/withdrawStarBalance" \
-H "Content-Type: application/json" \
-d '{"user_id": 1000456, "star_count": 200, "request_id": "prize-42"}'Ошибки: BALANCE_TOO_LOW (нечего выводить или запрошено больше доступного), STAR_COUNT_TOO_SMALL (меньше минимума сервера), STAR_COUNT_INVALID, REQUEST_ID_INVALID, REQUEST_ID_CONFLICT, BOT_OWNER_UNAVAILABLE (аккаунт владельца удалён или заморожен), STAR_WITHDRAWAL_DISABLED (вывод для бота отключён администрацией), Too Many Requests: retry after N (превышен лимит частоты, 429 с parameters.retry_after). Для user_id: Bad Request: user not found (USER_ID_INVALID — неверный id, пользователь не найден, удалён или системный), Bad Request: USER_IS_BOT, Bad Request: USER_FROZEN.
Возврат и вывод используют один баланс бота: если вывести всё, refundStarPayment вернёт BALANCE_TOO_LOW. Повторный возврат одного платежа — CHARGE_ALREADY_REFUNDED.
Выплаты пользователям
Как и в Telegram, в Bot API нет метода «перевести статики пользователю». Отдать пользователю ценность за статики бота можно так:
sendGift: подарок оплачивается с баланса бота. Получатель может оставить его или обменять на статики (сумма обмена указана в подарке,convert_star_count).giftPremiumSubscription: Premium за статики бота.refundStarPayment: только возврат конкретного платежа.
Бизнес-боты дополнительно могут transferBusinessAccountStars: перевести статики с подключённого бизнес-аккаунта на баланс бота (не пользователю).
Игры за статики
Отдельных правил для игр нет, действуют общие правила оплаты статиками:
- Вход в игру, попытки, внутриигровые покупки: обычный счёт в статиках. В HTML5-игре, открытой через
sendGame, нет JS-моста для оплаты, поэтому платные игры лучше делать как Mini App сopenInvoice, либо отправлять счётsendInvoiceв чат. - Выигрыш нельзя выплатить статиками напрямую (см. «Выплаты пользователям»): используйте подарки
sendGift. - Рекорды:
setGameScoreиgetGameHighScores, см. Игры.
Платёжные провайдеры и фиатные валюты: только статики (XTR) и коины (TON). Счета с доставкой (shipping_query никогда не приходит, answerShippingQuery отвечает QUERY_ID_INVALID). Счета через inline-результат (InputInvoiceMessageContent → 400 INVOICE_CONTENT_UNSUPPORTED).