To accept Telegram Stars for digital goods or services sold inside Telegram, send an invoice in currency XTR, validate and answer each pre_checkout_query within 10 seconds, then fulfill the order only after receiving successful_payment. Save Telegram’s payment charge ID with the order so you can identify it if a refund is needed. The Bot API workflow is language-neutral; the available PHP example covers provider-based payments, not a confirmed Stars implementation.
Check that Stars is the right payment flow
Telegram requires Stars for digital goods and services sold inside Telegram apps, even if the seller also operates a website or accepts other payment methods elsewhere. This guide is for those in-app digital purchases. Telegram directs physical-goods sellers to its separate payments documentation. See Telegram’s Bot Payments API for Digital Goods and Services.
As an Amazon Associate I earn from qualifying purchases.
For a digital-goods invoice, use currency XTR. Telegram’s Stars guide says provider_token is needed only for physical goods and services, so it can be left empty for digital sales. The Bot API changelog says to omit it for Stars in the relevant methods. Since PHP wrappers may serialize optional parameters differently, check the current method definition and the behavior of your exact library rather than assuming that an empty string and an omitted parameter are equivalent. See the Bot API changelog.
Stars payments were added in Bot API 7.4 on May 28, 2024, alongside the refundStarPayment method. That is historical release context, not a claim that Bot API 7.4 is the current version.
#1 Best Overall
Prepare an order record before sending the invoice
Create a pending order in your own system before the customer can check out. Include an invoice payload that identifies the order, along with the expected product, currency, and amount. Use the payload to associate later Telegram updates with the correct internal order.
Telegram documents the payload, currency, and total amount in the pre-checkout update. The amount is an integer in the currency’s smallest unit; for an XTR invoice, it is expressed in Stars. Your PHP handler should compare those reported values with the pending order before approving checkout. See Telegram’s pre-checkout query update definition.
Rank #2
Send the Stars invoice
Build the invoice using the Bot API method exposed by your PHP library, with XTR as the currency and the order-specific payload. Follow the method’s current parameter definition for provider_token; do not copy a provider-token setup from a conventional card-payment example and assume it applies to Stars.
Telegram’s API documentation does not prescribe PHP syntax or endorse a particular PHP package. Confirm that your chosen package supports Stars-specific invoice parameters and that it sends the payload in a form your update handler can read. Keep the pending order available before sending the invoice so that a quick checkout can be validated.
Validate and answer the pre-checkout query
When the user proceeds with payment, Telegram sends a pre_checkout_query. Match its payload to a pending order and verify that the order is still eligible, and that the reported currency and integer amount agree with what you stored. Approve only a valid match.
- Receive the update. Route
pre_checkout_queryupdates to a handler in your bot. - Validate the order. Look up the pending order by its payload; check its status, expected product, currency, and amount against the update.
- Respond within 10 seconds. Call
answerPreCheckoutQuerypromptly. If you cannot process the order, reject it with a human-readable reason; Telegram displays that reason to the user.
Telegram cancels a checkout that is not answered in time. Keep this handler short enough to meet the deadline; do not wait for slow work that is unnecessary to decide whether to approve the order. See Telegram’s step-by-step Stars payment process.
Rank #4
Fulfill only after Telegram confirms payment
An approved pre-checkout query is not proof that the payment succeeded. Wait for the successful_payment update before delivering the digital item or enabling the service. Telegram explicitly warns: “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.”
Recommended Free Tools
When processing the successful-payment update, associate it with the order and record Telegram’s telegram_payment_charge_id. Telegram says this identifier may be required for a future refund; its Stars guide points to refundStarPayment for digital-goods refunds. See Telegram’s Stars refund guidance.
What to verify in a PHP library
The API rules above apply regardless of implementation language, but package support and update parsing are library-specific. A PHP example repository separates payment and pre-checkout commands and describes generic post-payment messaging, yet its setup uses a payment-provider token and covers traditional payments; it does not establish a Stars-ready implementation. Review its payment example README as an example of that distinction, not as a Stars recipe.
- Confirm the library version supports Stars invoices with
XTRand handles the optionalprovider_tokenas Telegram currently specifies. - Check how it parses and dispatches
pre_checkout_queryandsuccessful_paymentupdates. - Verify that the invoice payload is available to your handler and can be mapped to your pending order.
- Confirm that the successful-payment data exposes
telegram_payment_charge_idand that your integration can call the refund method if needed.
Do not treat a provider-based PHP example as evidence that Stars support works in a particular package. The Telegram documentation defines the required API behavior; the package’s current version and serialization determine how to implement it in PHP.
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.
