Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteA Stars sale in a PHP bot is a four-part loop. Your bot sends an invoice with currency XTR, answers the pre_checkout_query within 10 seconds, delivers the goods only after a successful_payment update arrives, and stores the telegram_payment_charge_id so you can handle support requests and refunds later.
Know the rules before writing code
Telegram’s Stars guide says digital goods and services sold inside Telegram apps must be paid for with Stars. The Bot API changelog records that Bot API 7.4 added Stars support, using the XTR currency code, and introduced the refundStarPayment method on May 28, 2024. Those are the two anchors for everything below.
As an Amazon Associate I earn from qualifying purchases.
Telegram’s public documentation describes the Bot API payment lifecycle. It does not provide PHP code, name a preferred PHP library, or describe how a particular framework dispatches webhook updates. Treat the examples in this guide as a map of the flow. Check method names, parameter types, and webhook setup against the Bot API method reference and against the current documentation of the PHP client you use.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Step 1: Create the Stars invoice
Call sendInvoice with the parameters below. The table shows what a Stars invoice needs; your client may wrap these in its own method signature.
#1 Best Overall
| Parameter | Value for a Stars invoice | Notes |
|---|---|---|
chat_id |
The buyer’s chat ID | Identifies where the invoice is sent. |
title and description |
Short product name and a sentence about what the buyer gets | Shown to the buyer on the invoice. |
payload |
Your internal order reference | Telegram returns this value in the pre-checkout query. Use it to look up the order on your server. Do not put the price in it. |
currency |
XTR |
Stars currency code, introduced with Bot API 7.4. |
prices |
One labeled price whose amount is the Star count | The amount is set on your server from your own price list. |
provider_token |
Follow your client’s signature | Sources differ on this field. The Stars guide says to leave it empty, while the Bot API changelog says it must be omitted for Stars invoices. Check the current changelog and your client’s signature, and do not send a token for a Stars invoice unless your client requires the field. |
Create the order record on your server before you send the invoice, with the product, the Star amount, and a status such as pending. Build the price from server-side data. Never accept a price from the client, and do not treat the invoice message in the chat as proof of purchase.
Step 2: Validate the pre-checkout query
When the buyer taps Pay, Telegram sends a pre_checkout_query update. It contains the query ID, the buyer, the currency, the total amount, and the invoice payload. Use these fields to check the order:
- The
invoice_payloadmatches an order that is still pending. - The
currencyisXTR. - The
total_amountequals the price stored for that order. - The item is still available and the buyer is not already entitled to it.
Call answerPreCheckoutQuery with the query ID and ok=true if all checks pass. The Bot Payments API documentation sets a deadline of 10 seconds for this answer, and the method reference repeats that deadline. Keep the handler fast. Do not call slow external services from inside it.
Rank #2
If the order cannot be fulfilled, send ok=false with an error_message that a buyer can read, such as “This item is sold out.” Telegram displays that text to the buyer.
Telegram’s payment guide also warns that multi-use and forwarded invoices require the merchant to decide whether to accept each payment. If your bot sells one-time items, your pre-checkout check should reject a second payment for the same order.
Step 3: Wait for successful_payment before delivering
Approving pre-checkout does not prove the money moved. Telegram’s Stars guide puts it directly: “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.” That warning is part of Telegram’s official documentation and is not attributed to a named person.
The successful_payment field arrives inside a message update. Before you deliver anything, check that:
Recommended Free Tools
- The currency is
XTR. - The total amount matches the order.
- The invoice payload matches an order that is pending or paid.
- No other order already uses the same
telegram_payment_charge_id.
Then mark the order as paid and deliver the goods. Make this step idempotent. Your webhook or polling loop may receive the same update more than once, and a retry must not grant the item twice. A unique database index on the charge ID is the simplest protection. Confirm your client’s behavior on duplicate delivery before you rely on it.
Step 4: Store the charge ID, then handle support and refunds
Save telegram_payment_charge_id with the order at the moment you mark it paid. The Stars guide says you may need it for a later refund, so a record without it cannot be refunded through the documented method.
Rank #4
Customer support with /paysupport
Telegram assigns the handling of legitimate payment disputes to the merchant, and your bot must respond to the /paysupport command. Build a reply that tells the buyer how to reach you, what information to include, and what the usual timeline is. Your handler should look up the buyer’s orders so you can answer quickly.
Refunds with refundStarPayment
Use refundStarPayment when a refund is appropriate. It was added in Bot API 7.4 and needs the stored charge ID. Decide your refund policy before you need it, and record the refund on the order so the item cannot be delivered again after a refund.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Webhooks, long polling, and your PHP client
Whether you receive updates by webhook or long polling depends on the client you choose and how you deploy the bot. The payment sources do not settle that choice, and they do not describe retry behavior, update parsing, or how duplicate deliveries are handled. Check these points in your client’s documentation before you ship:
- How the client sets the webhook, and whether it lets you list the update types you want, including
pre_checkout_queryandmessage, which carriessuccessful_payment. - How it turns the incoming JSON into update objects, and whether it exposes
pre_checkout_queryandsuccessful_paymentas typed fields. - Whether Telegram retries a failed webhook delivery, and how the client reports a failed handler.
- Which method signature it uses for
sendInvoiceand whether it sends or omitsprovider_tokenfor Stars.
Name the client and version in your own code and tests. Client APIs change, and the Stars parameters changed with Bot API 7.4.
Troubleshooting checklist
- The buyer sees an error after tapping Pay. Your pre-checkout handler did not answer in time or returned
ok=false. Time the handler, and check the order payload and amount. - The buyer paid but received nothing. The bot did not process
successful_payment. Confirm that your webhook includes themessageupdate type and that your handler delivers the item on that event. - The item was delivered twice. Your fulfillment step is not idempotent. Add a unique constraint on the charge ID and check it before delivery.
- A refund cannot be issued. The charge ID was not stored with the order. Recover it from your logs or from the stored update payload, if you kept one.
- A buyer asks for help with
/paysupportand gets no reply. The command handler is not registered or your webhook does not receive messages. Test the command on a live bot.
Test the full path on a test bot with a small Stars price before you open the bot to buyers. Confirm each event in order: invoice, pre-checkout, successful_payment, stored charge ID, and delivery.
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.
