Choosing between Telegram Stars and fiat payment providers
Telegram separates payments into two distinct categories based on what is being sold. Digital products, virtual services, access to private channels, and in-bot consumables must use Telegram Stars with currency code XTR under Telegram terms and mobile platform policies. Physical goods and real-world offline services use traditional fiat payment providers connected through BotFather.
For fiat transactions, Bot API supports gateways such as Stripe and others via provider tokens. For Telegram Stars, the provider token is omitted in API requests, and payments settle directly within the Telegram ecosystem. If you are still deciding whether you need a bot at all, start with Telegram bot for business.
How invoices work in Bot API
Invoices can be delivered directly in chat messages using sendInvoice or generated as standalone URLs via createInvoiceLink for Telegram Mini Apps and external buttons. Each invoice defines the currency, labeled price items, and an internal payload string.
The payload parameter carries your internal purchase identifier, account reference, or cart hash. Telegram does not display the payload to the buyer, but returns it untouched in subsequent payment updates so your backend can match the transaction. Payments inside a Mini App are covered in Telegram Mini Apps.
The two-step checkout flow: pre_checkout_query and successful_payment
Bot API enforces a two-step validation model to protect transactions before money moves:
- pre_checkout_query: When the user presses Pay, Telegram sends this update to your bot. The server must verify inventory, pricing, and account status, then call answerPreCheckoutQuery with ok=true or an error message within ten seconds.
- successful_payment: After the transaction is confirmed by Telegram or the payment gateway, the bot receives a message containing currency, total amount, invoice payload, telegram_payment_charge_id, and provider_payment_charge_id.
Webhook reliability and idempotency
Telegram delivers payment updates over HTTPS webhooks. If your endpoint responds with an HTTP error or times out, Telegram retries sending the update. Without strict idempotency, a retried update can trigger duplicate delivery of digital assets or double fulfillment. The difference between webhooks and long polling is covered in webhook vs long polling.
Store the unique telegram_payment_charge_id or provider_payment_charge_id in a unique database column. Process fulfillment inside a database transaction that verifies whether the charge identifier has already been recorded, and immediately return HTTP status 200 once the update is accepted.
Handling refunds and payment disputes
Refund mechanics depend on the payment method used for the order. For transactions paid in Telegram Stars, the Bot API provides the refundStarPayment method, which requires the user ID and the original telegram_payment_charge_id. When called successfully, the Stars return to the user balance and the charge status updates.
For fiat gateways such as Stripe, refunds cannot be executed through Bot API methods. Your backend must call the payment provider REST API directly or process the refund through the provider merchant portal using the stored provider_payment_charge_id. Payment logic is one of the factors in Telegram bot development cost, and we build such bots as part of the Telegram bot development service.
Core security practices for payment bots
A production payment bot requires baseline security controls at the network and application layers:
- Validate webhook authenticity using the secret_token header configured in setWebhook.
- Never calculate final prices or order contents on the client side; compute totals exclusively on the backend.
- Isolate billing handlers from long-running tasks by acknowledging webhooks first and offloading processing to a background worker queue.
- Log charge identifiers, payloads, and response statuses for auditability without storing sensitive payment credentials.