The Stars were charged and on_paid never ran: where Telegram Stars payments get lost in aiogram

Description and use

The aiogram-stars library handled Telegram Stars payments, but due to bugs in asyncio timeout handling, router ordering, and dispatcher shutdown, the on_paid handler never ran, causing lost payments. After fixing nine bugs, the library now reliably processes payments, creates database records, and handles refunds correctly.

Problem

Telegram Stars payments are accepted but the bot’s on_paid handler never runs, causing lost payments and no database record.

Outcome

After identifying nine bugs, the library now reliably processes Stars payments, ensuring on_paid runs, database rows are created, and refunds are handled correctly.

Workflow

• 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.

Evidence

A buyer pays 100 Stars, Telegram takes them, and the bot replies to the payment message with "Sorry, I don't know this command".

Source

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.

Source

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.

Source

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.

Source