Skip to content
← All articles
6 min read

Telegram bot payments: architecture, payment providers and reliable processing

Implementing telegram bot payments requires understanding the distinction between digital and physical goods, two-step checkout validation, and idempotent update processing. Here is the technical breakdown of how to build reliable payment workflows using the Bot API.

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

FAQ

Didn't find an answer — ask on the call or in Telegram.

Can a bot accept both fiat currency and Telegram Stars?

Yes, but not within the same invoice. A bot can generate separate invoices: one in fiat currency via a provider token for physical products, and another in XTR for digital content. Your backend routes the user to the correct invoice type based on the product category.

What happens if answerPreCheckoutQuery is not sent in time?

Telegram cancels the checkout process and displays a timeout error to the user. The user account is not charged. The timeout threshold is ten seconds, so validation logic must run quickly without waiting for slow external dependencies.

Is Bot API payment data accessible to the bot developer?

The bot receives transaction identifiers, currency, amount, and the invoice payload. Sensitive payment details such as card numbers or bank credentials are handled entirely by Telegram and certified payment gateways and are never exposed to the bot.

Which payment gateway can a Telegram bot use?

For physical goods and offline services the bot uses a fiat payment provider connected through BotFather, such as Stripe, and the invoice carries the provider token. Digital goods are sold in Telegram Stars (XTR) without a provider token. Which providers are available depends on the country and the provider’s terms, so we check this before development starts.

Related service

Telegram bot development for business

A bot is a way into your system in the place where customers and staff already talk. We build bots as full applications — with a database, permissions and integrations — not as a set of buttons.

Learn about the service
Other articles
Contact

Shall we discuss your task?

Thirty minutes on a call — and you understand the architecture, timeline and engagement format. No obligations.

Or message us on Telegram →Follow our Telegram channel →

Enter your Telegram or email so we can reply.

We reply within 15 minutes.