The Stars were charged and on_paid never ran: where Telegram Stars payments get lost in aiogram
Описание и применение
Библиотека aiogram-stars обрабатывает платежи Stars в Telegram, но из‑за ошибок в тайм‑ауте, порядке роутеров и завершения диспетчера on_paid не запускался, что приводило к потере платежей. После исправления девяти ошибок библиотека теперь надёжно обрабатывает платежи, создаёт записи в базе и корректно обрабатывает возвраты.
Задача
Telegram Stars payments are accepted but the bot’s on_paid handler never runs, causing lost payments and no database record.
Результат
After identifying nine bugs, the library now reliably processes Stars payments, ensuring on_paid runs, database rows are created, and refunds are handled correctly.
Рабочий процесс
- 1. Buyer initiates a Stars payment, triggering a pre_checkout_query update.
- 2. Bot answers the pre_checkout_query within a 10‑second deadline using asyncio.wait_for to enforce a timeout.
- 3. If the check function succeeds, Telegram sends a successful_payment update.
- 4. The on_paid handler is invoked to deliver goods and record the transaction.
- 5. If any step fails (timeout, router conflict, dispatcher shutdown, or refund queue flood), the payment is lost or refunded.
Доказательства
A buyer pays 100 Stars, Telegram takes them, and the bot replies to the payment message with "Sorry, I don't know this command".
That bug never made it into a release. Before I published the first version, I went through it again with one question: where can a payment get lost here? I found nine bugs.
The library does the rest. The invoice payload carries an HMAC over the order id and the amount, so a payload made elsewhere or paid with another amount is declined before check runs.
The first version did this with asyncio.wait_for... If check holds a database connection and rolls back in finally on that same hung connection, wait_for waits for the rollback too.
- Дата записи: 2026-10-18T12:40:59.317Z