iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To accept Telegram Stars for digital goods or services inside Telegram, send an invoice in currency XTR, answer its pre_checkout_query within 10 seconds, and deliver the purchase only after receiving a successful_payment update. Keep an internal order record tied to the invoice payload and save Telegram’s payment charge ID for possible refunds.
Before you build: Stars are for in-app digital sales
Telegram requires digital goods and services sold inside Telegram apps to use Stars, even when the seller also has a website or accepts other payment methods elsewhere. This guide is limited to those in-app digital purchases; physical goods and services use Telegram’s separate payment workflow. See Telegram’s Bot Payments API for Digital Goods and Services.
The workflow is defined by Telegram’s language-neutral Bot API. The available PHP example repository demonstrates a traditional provider-token payment flow, not a Stars-ready implementation, so its provider setup should not be copied into a Stars invoice without checking the Stars-specific rules.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →What the PHP bot needs to do
- Create and send an invoice. Use currency
XTRfor a digital purchase paid with Stars. Give the invoice a bot-defined payload that identifies the internal order. - Validate and answer the pre-checkout query. When Telegram sends
pre_checkout_query, check the pending order against the payload, currency, and total amount, then approve or reject it within 10 seconds. - Fulfill after payment confirmation. Wait for a
successful_paymentupdate before delivering anything, and recordtelegram_payment_charge_idwith the order.
Build and send the Stars invoice
For an in-app digital sale, set the invoice currency to XTR. Telegram’s Stars guide says provider_token is needed only for physical goods and services; for digital sales it can be left empty. The Bot API changelog says to omit the parameter for Stars in the relevant methods. Those instructions are not necessarily interchangeable in every PHP wrapper: check the current Bot API method definition and how your chosen library serializes optional parameters.
#1 Best Overall
Include a payload you control so later updates can be matched to the order your application created. Before the buyer can finish checkout, store the order’s expected product, currency, amount, and pending status where your update handler can retrieve them. Telegram documents the payload in the pre-checkout update, but the PHP library you use determines how that update is exposed in code.
Validate and answer pre_checkout_query
When a user proceeds to payment, Telegram sends a pre_checkout_query. It contains the invoice payload, currency, and total amount. Telegram defines total_amount as an integer in the smallest unit of the currency; for Stars invoices, the currency is XTR and the amount is expressed in Stars. See Telegram’s pre-checkout query update fields.
Rank #2
Use the payload to find the pending order and compare the incoming currency and amount with the values you stored. Approve only if the order is valid and still processable. Otherwise reject the query with a human-readable reason; Telegram displays that reason to the user.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Send the answer through answerPreCheckoutQuery within 10 seconds. Telegram cancels checkout if the bot does not answer in time, so keep this handling path fast and avoid work that is not needed to approve or reject the order. See Telegram’s payment workflow documentation.
Fulfill only after successful_payment
Approving pre-checkout is not confirmation that the payment completed. Wait for the successful_payment update before delivering the digital item or enabling the service. Telegram states: “You must always check that you received a successful_payment update before delivering the goods or services purchased by the user – simply answering a pre_checkout_query does not guarantee a successful order or payment.”
When handling that update, associate the payment with the order and persist Telegram’s telegram_payment_charge_id. Telegram says this identifier may be needed for a future refund and documents refundStarPayment for refunds of digital-goods payments. See the Stars payment and refund guidance.
Rank #4
Check your PHP library’s Stars support
The Bot API requirements do not depend on PHP, but a PHP wrapper controls how you construct method parameters, parse updates, and dispatch handlers. The located php-telegram-bot example-bot README separates payment and pre-checkout commands and describes post-payment handling, but its setup uses a payment-provider token for traditional payments; it does not establish a Stars-ready PHP implementation.
Recommended Free Tools
Before adapting a library, verify its exact version and confirm that it can:
- Send Stars invoices using
XTRand the correct treatment ofprovider_token. - Parse the payload, currency, and total amount from pre-checkout updates.
- Answer pre-checkout queries and dispatch
successful_paymentupdates to your handlers. - Expose the Telegram payment charge ID and support the refund method if your application needs refunds.
Bot API 7.4 introduced Stars payments under XTR and the refundStarPayment method on May 28, 2024. That date is historical release context, not an indication of the current Bot API version; consult Telegram’s Bot API changelog and the documentation for your installed PHP library.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
