Architecture Overview

A Telegram Stars payment flow has three distinct phases. First, the bot sends an sendInvoice request containing a unique lead identifier and an HMAC-protected initData . The lead identifier is a 14-character hex string generated with bin2hex(random_bytes(7)) and stored in a database. Second, when the user taps the MainButton, the bot calls pre_checkout_query to verify the invoice hasn't been replayed, the bot token is still valid, and the auth_date is fresh. Third, on successful payment, successful_payment is invoked to mark the invoice as paid, update the lead state, and send a confirmation. If any step is skipped or validated incorrectly, an attacker can forge an initData and redirect funds to their own account.

sendInvoice — Create the Invoice

The sendInvoice function creates a Telegram Invoice object and returns the data field that the bot will send to the user.…