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 sell digital goods for Telegram Stars from a PHP bot, create an invoice with currency XTR, answer the pre_checkout_query within 10 seconds, and deliver the purchase only after a successful_payment update arrives. Approving the pre-checkout step does not prove that payment succeeded, so fulfillment belongs in the handler for successful_payment.
Telegram’s official documentation describes this Bot API lifecycle but does not provide PHP code, name a PHP library, or explain how a framework dispatches webhook updates. The steps below use Bot API method and update names, which you map to the function signatures of your own PHP client.
The payment lifecycle in order
- Create the invoice. Send an invoice with currency
XTR. Telegram’s Stars guide says Stars are required for digital goods and services sold inside Telegram apps. - Validate the pre-checkout query. When the customer confirms, your bot receives a
pre_checkout_query. Check the invoice payload and your current order state, then callanswerPreCheckoutQuery. - Wait for the successful payment update. Telegram sends a
successful_paymentupdate once the payment completes. Deliver the goods or services at this point. - Store the payment identifier. Save
telegram_payment_charge_idfrom the successful payment with the order record. - Handle support and refunds. Respond to
/paysupportand userefundStarPaymentwhen a refund is appropriate.
Step 1: Creating a Stars invoice
The currency code for Stars is XTR. Telegram’s documentation is not consistent about the provider_token parameter for these invoices, and the two sources you will find say different things:
| Telegram source | What it says about provider_token |
|---|---|
| Bot Payments Stars guide | May be an empty string for digital-goods invoices |
| Bot API changelog (Bot API 7.4 entry) | Must be omitted for Stars invoices |
Follow the current method schema in the Bot API reference and the signature exposed by your PHP client. If your client requires the parameter, check its documentation for how to leave it unset. Do not copy a value from an older tutorial without checking it.
#1 Best Overall
Step 2: Validating pre-checkout
The pre_checkout_query contains the invoice payload, the currency, and the total amount. Treat these as values to verify, not as facts you can trust. Compare them with the price and state you stored on the server when the order was created. Do not rely on the price shown in the invoice message.
Your handler should:
- Look up the order referenced by the payload and confirm it is still unpaid and still available.
- Confirm that the currency is
XTRand the amount matches the stored total. - Answer with
answerPreCheckoutQuerywithin 10 seconds. This deadline is stated in Telegram’s Bot Payments API documentation and repeated in the method reference. Avoid slow remote calls before you answer. - When rejecting, include a short, human-readable reason. The customer sees it.
Telegram’s payment guide also notes that multi-use and forwarded invoices leave the decision to the merchant. Your bot should decide for each payment whether to accept it, rather than approving every query by default.
Rank #2
Step 3: Fulfilling only after successful_payment
Telegram’s Stars guide states the rule directly: check that you received a successful_payment update before delivering the goods or services, because answering a pre_checkout_query does not guarantee a successful order or payment. Make this the only path that marks an order as paid and unlocks the product.
Telegram’s documentation does not specify how often an update may be delivered more than once, or how a PHP client handles retries. Build your own protection. A practical approach is to store telegram_payment_charge_id with a unique constraint and to mark the order as fulfilled in the same database transaction. A repeated update then fails the constraint instead of delivering the product twice.
Recording payments and issuing refunds
Keep telegram_payment_charge_id with the order, because the Stars guide notes it may be needed for a later refund. Telegram added Stars support and the refundStarPayment method in Bot API 7.4, recorded in the Bot API changelog with a date of May 28, 2024. Use the method when a refund is appropriate for the order, and pass the stored charge identifier.
Customer support and disputes
Telegram assigns support for legitimate disputes to the merchant. Your bot must respond to the /paysupport command, so set up a handler for it and give the customer a clear way to request help with a payment. Pair that handler with your order records, so support staff can locate the payment by its charge identifier.
Rank #4
Webhooks, polling, and your PHP client
Telegram’s payment documentation covers the API lifecycle, not the transport. Whether your bot receives updates through a webhook or through long polling depends on the PHP client you choose. Telegram’s sources do not settle which option suits a given framework. Before writing code, confirm in your client’s documentation:
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 →- How webhooks are registered, and how the client parses an incoming update into an object.
- Whether the client exposes
pre_checkout_queryandsuccessful_paymentas distinct update types. - How the client handles failed deliveries and duplicates, if it does at all.
- The exact method names and parameters for
sendInvoice,answerPreCheckoutQuery, andrefundStarPayment.
Troubleshooting checklist
- The customer paid, but nothing was delivered. Check that your
successful_paymenthandler runs. Pre-checkout approval alone does not deliver anything. - The payment failed at confirmation. Confirm that
answerPreCheckoutQueryis sent within 10 seconds of the query. - Invoice creation fails with a provider or token error. Compare your call with the current method schema, and check whether your client adds
provider_tokenautomatically. - A product was delivered twice. Add a unique constraint on
telegram_payment_charge_id, since the sources do not describe duplicate-delivery behavior. - A customer asks for a refund. Locate the stored charge identifier first, then use
refundStarPayment.
Before going live, test the full path with a small Stars invoice on a test bot, confirm that each update type reaches the correct handler, and verify your order state changes at each step.
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.
