Принимать оплату в звёздах: счета, подписки и возвраты

Что это

Цифровые товары и услуги в ботах и мини-приложениях продаются только за звёзды Telegram — валюта `XTR`. Бот выставляет счёт, подтверждает заказ при оплате, выдаёт товар после неё и хранит номер платежа на случай возврата. Один параметр превращает ссылку на счёт в подписку на 30 дней.

Как сделать

1. Счёт — `sendInvoice`, ссылка на счёт — `createInvoiceLink`: `currency` = `XTR`,… Счёт — `sendInvoice`, ссылка на счёт — `createInvoiceLink`: `currency` = `XTR`, пустой `provider_token`, в `prices` ровно одна позиция, в `payload` номер заказа.
2. Подписка: добавь в `createInvoiceLink` `subscription_period` = 2592000 (30 дней).
3. В мини-приложении открой ссылку через `openInvoice`: событие `invoiceClosed`… В мини-приложении открой ссылку через `openInvoice`: событие `invoiceClosed` вернёт `paid`, `cancelled`, `failed` или `pending`.
4. На `pre_checkout_query` ответь `answerPreCheckoutQuery`: `ok` = true или false… На `pre_checkout_query` ответь `answerPreCheckoutQuery`: `ok` = true или false с `error_message`, который увидит покупатель.
5. Выдавай товар только после `successful_payment` и сохрани… Выдавай товар только после `successful_payment` и сохрани `telegram_payment_charge_id`. В платежах по подписке есть ещё `is_recurring`, `is_first_recurring` и `subscription_expiration_date`.
6. С июля 2026 года обновление `subscription` сообщает, что подписка стала `canceled`, `active` или `failed`.
7. Возврат — `refundStarPayment`; возвраты приходят служебными сообщениями… Возврат — `refundStarPayment`; возвраты приходят служебными сообщениями `refunded_payment`. `editUserStarSubscription` отменяет продление или позволяет человеку снова включить подписку, которую отменил бот.
8. Сверяй деньги через `getStarTransactions` и `getMyStarBalance`.

Осторожно

• На `pre_checkout_query` нужно ответить за 10 секунд, иначе платёж отменится.
• `payload` — 1–128 байт, `title` — 1–32 символа, `description` — 1–255; чаевые в звёздах не работают.
• Подписка стоит не больше 10 000 звёзд; у одного человека их может быть несколько.
• `getStarTransactions` отдаёт 1–100 записей за вызов.
• При чарджбэке звёзды могут списать с твоего баланса даже после `successful_payment`.
• Сначала всё проверь в тестовой среде Telegram.

С Gem

Gem не выставляет счета от имени твоего бота: своего бота к Gem пока не подключить. В проекте на Gem звёзды за твои предложения принимает @gembot, которого держит Gem, — раздел /myprojects › Sell.

Источники

• https://core.telegram.org/bots/payments-stars
• https://core.telegram.org/bots/api#payments
• https://core.telegram.org/bots/webapps#initializing-mini-apps
• https://core.telegram.org/bots/api-changelog#july-14-2026

Открыть в Telegram ↗