serejaris/telegram-skills / skills/tg-stars-payments
tg-stars-payments
VerifiedUse when a Telegram bot or Mini App sells digital goods for Stars (XTR): invoices and invoice links, openInvoice, pre_checkout_query, crediting on successful_payment without double delivery, refunds and /paysupport, 30-day subscriptions, paid media, testing payments, Star payout figures.
tg-stars-payments
Checked against the official docs on 2026-10-30: Bot API 10.3 (August 24, 2026), the Stars payments guide and the developer terms § 6.2. Nothing here was run against a live bot, see Not verified live.
Digital goods and services sold inside Telegram apps go through Stars only: currency XTR, empty provider_token. Physical goods use a provider, see Payments. Payout rates, the hold, expiry and the 15% topics fee live in references/stars-economics.md; read it before quoting money or enabling topics in private chats.
Purchase flow
- Subscribe. The active
allowed_updatesincludesmessageandpre_checkout_query, plussubscriptionandpurchased_paid_mediawhen you sell those. An omitted list keeps the previous setting, seetg-bot-ops. A bot withoutpre_checkout_querylets every checkout time out. - Create the invoice (table below). Put an order id in
payload(1-128 bytes). The title is 1-32 characters, the description 1-255,priceshas exactly one item, amounts are whole Stars. - Answer pre-checkout within 10 seconds with
answerPreCheckoutQuery, or the transaction is canceled. Answer it in the handler itself, outside any update queue: a queue that lags 10 seconds cancels the purchase. Check stock and order state, not delivery. Onok: falsepasserror_message; Telegram shows it to the user. - Credit on
successful_paymentonly. It arrives as a service message. Answering pre-checkout proves nothing; a Mini Apppaidstatus is a hint for the UI. - Store first, deliver second. See Recording and delivery.
- Support. The bot answers
/paysupport, and refunds through Refunds.
Done when: a repeated successful_payment starts no new delivery, two parallel handlers claim a payment once, and a crash between storing and delivering returns the order to the queue.
Creating the invoice
| Surface | Method | Notes |
|---|---|---|
| Chat of any type | sendInvoice | The first inline button must be Pay. Does not take subscription_period |
| Mini App, website, your own link | createInvoiceLink, then Telegram.WebApp.openInvoice(url, callback) | Required for subscriptions |
| Inline mode | inputInvoiceMessageContent | Always a multi-chat invoice |
For Stars the need_*, send_*_to_provider and is_flexible fields are ignored, tips are not supported.
Forwarded copies. Empty start_parameter: forwarded copies keep Pay, several people can pay one invoice. Non-empty: forwards get a deep link to the bot. A single-chat invoice in the chat with the bot is payable once; in any other chat it can be paid many times. In every multi-use case the guard is your pre-checkout answer: accept a second payment only when the order can run twice.
Link host. Keep the URL from createInvoiceLink out of allowlists and regexes: the host can change. The link the API returns may still fail to open. During the t.me outage on 2026-07-14 a practitioner saw the method return telegram.me, the invoice did not open, and only replacing the host by hand helped (PTB #5296, practitioner report). Open a real invoice on a client before and after any workaround.
Mini App.
invoiceClosedstatuses arepaid,cancelled,failedandpending. Onpendingthe payment is still processing; wait forsuccessful_paymenton the server.- Call
openInvoicefrom the Mini App's own domain. Since July 20, 2026 Mini App methods are disallowed from other origins, opt-out in @BotFather (Bot API 10.2). - Take the buyer from the signed
initDataon your server, never frominitDataUnsafe(seetg-miniapp-launch-auth). Thesuccessful_paymentsender is the final answer. - On Telegram Desktop a Stars invoice with an insufficient balance can fail with
PROVIDER_ACCOUNT_INVALIDfor third-party bots (tdesktop #31262, practitioner report, open on 2026-10-30).
Recording and delivery
One payment gets one ledger row and one live claim. Delivery itself runs at least once: a crash after your deliver and before the mark repeats it after the lease. The buyer gets one product only when deliver is idempotent by payment.key, or when the credit shares a transaction with the mark.
The key is telegram_payment_charge_id. It is the identifier the docs tell you to store, and StarTransaction.id equals it for incoming user payments, so getStarTransactions can reconcile against your ledger.
update_id is no key for money. A Bot API maintainer: it "can't be used as an idempotency key for payments", it only orders updates and discards duplicates (tdlib #837, 2026-03-27). After a week without updates the next update_id is chosen randomly. A practitioner reports repeated successful_payment deliveries (dev.to, self-report, not reproduced here).
Renewals. The docs do not say whether a subscription renewal gets a new charge id. Key on telegram_payment_charge_id plus subscription_expiration_date (0 for one-time payments): that credits each period once under either behavior.
scripts/stars_ledger.py is a network-free SQLite reference with tests. A row moves through pending, claimed, delivered, with refunded reachable from each:
import stars_ledger as ledger
conn = ledger.connect('/var/lib/mybot/stars.sqlite3') # one connection per worker
payment = ledger.parse_payment(update) # None for other updates, ValueError for a broken payment
if payment:
ledger.record_payment(conn, payment) # durable on return, acknowledge the update after this
for due in ledger.pending(conn, now=int(time.time())): # also run on a timer
if not ledger.claim(conn, due, now=int(time.time())):
continue # another worker holds it
try:
deliver(due, idempotency_key=due.key)
except Exception as error:
ledger.release(conn, due)
log_and_alert(due.key, error) # the next rows still go out
continue
if not ledger.mark_delivered(conn, due) and ledger.state(conn, due) == ledger.REFUNDED:
revoke(due) # the refund landed during delivery
One failing row must not stop the pass: a buyer who blocked the bot fails on every pass, and everyone who paid later waits behind that row. The alert is how a person learns about a row that keeps returning.
mark_delivered returns False in two cases, so read state before acting. refunded means the buyer has the Stars back and the goods went out, so revoke them. delivered means the lease ran out and another worker finished under the same key, so the grant stands.
Contract of the helper:
- A file path is required.
connectrefuses:memory:: a restart would erase paid orders, and a repeated update would pass as a new purchase. Telegram's live checklist asks you not to lose payment data. - Each call commits on its own. The ledger runs in autocommit, so no call leaves a write lock open. Use
with ledger.transaction(conn):to join an order insert withrecord_payment. claimis one conditionalUPDATE. With parallel webhooks (max_connectionsdefaults to 40)pendingshows the same row to every handler, and only oneclaimreturnsTrue. Delivering straight frompendingdelivers twice.- The lease replaces a reset on startup. A startup reset would take claims away from workers still running. A crashed worker's row returns once
lease_untilpasses (300 seconds by default). Set the lease longer than the slowestdeliver. - Internal balance. Credit only when the mark succeeds, inside one transaction: a crash undoes both, and a refund or another worker that got there first leaves the balance untouched:
with ledger.transaction(conn):
if ledger.mark_delivered(conn, due):
credit_balance(conn, due.user_id, due.amount)
Keep the unique key and the conditional claim in your own schema if you adopt the logic elsewhere. Acknowledge the update only after record_payment returns (see tg-bot-ops); a dropped successful_payment is money taken and nothing delivered.
Recovery from getStarTransactions
Use it after a lost update, after drop_pending_updates, and for dead-lettered payments. Page with offset and limit 1-100 and pass each StarTransaction to ledger.reconcile_transaction(conn, transaction, since=failure_time).
since is required: set it to the Unix time of the failure, or to the moment the ledger went live if that is later. Transactions older than since return False. On a bot that sold before the ledger existed, a full history would queue every past buyer for delivery again.
StarTransaction has id, date and, in TransactionPartnerUser, subscription_period. It has no subscription_expiration_date, which is half of the ledger key, so a renewal can't be rebuilt exactly. The helper matches by these rules:
- Search by
charge_idfirst. One-time payments match on the key. - For a subscription, a row with the same
charge_idis the same period whensubscription_expires_at - subscription_periodfalls within half a period ofdate. Periods of one subscription lie a full period apart. - With no match, store a row with the estimate
date + subscription_periodand remember the period. - A late
successful_paymentwithin half a period of that estimate returnsFalse, so delivery doesn't start again. It replaces the estimate with the true expiry, unless the row isclaimed: the running delivery holds that key as its idempotency key, so the estimate stays. - An outgoing transaction to a user carries the id of the refunded payment and goes to
record_refund.
A refund for a charge the ledger hasn't seen yet is stored and applied when the payment arrives, by update or by recovery, so that row never reaches delivery. Until the estimate is replaced, grant access by subscription_expires_at knowing it can be off by the gap between the renewal and the old expiry.
Refunds and disputes
refundStarPayment(user_id, telegram_payment_charge_id)returns the Stars in full; there is no partial-amount parameter. "invalid user_id specified" meansuser_idnever reached the server: a wrapper bug (tdlib #789, maintainer, 2025-11-16).- A refund shows up as a
refunded_paymentservice message, handle it withparse_refund_charge_idandrecord_refund, and revoke access. /paysupportis mandatory (terms § 6.2.1). Failing to resolve legitimate disputes can lead to Stars debited from the balance, removal, a public SCAM label and account termination. Tell users that Telegram support will not help with purchases, and offer/terms(Live Checklist).- A buyer's chargeback with Apple or Google deducts the Stars from your balance (StarTransaction). Telegram discourages real-time sale of goods that can't be revoked after a chargeback (§ 6.2.1). Prefer access you can withdraw.
Subscriptions
createInvoiceLinkwithsubscription_period: 2592000, the only allowed value (30 days), at most 10000 Stars. One user may hold several at once.- Each paid period arrives as
successful_paymentwithis_recurring,subscription_expiration_dateand, on the first one,is_first_recurring. Grant access untilsubscription_expiration_date, and match periods byinvoice_payload. subscriptionupdate (BotSubscriptionUpdated, Bot API 10.2):stateiscanceled,active(re-enabled) orfailed. It carriesuserandinvoice_payload, no charge id, so keep a unique payload per subscription.canceledkeeps access until the end of the paid period.editUserStarSubscription(user_id, telegram_payment_charge_id, is_canceled)lets the bot stop or restore renewal.
Paid media
sendPaidMedia: star_count 1-25000, up to 10 items, payload 0-128 bytes. In a channel the Stars go to the channel's balance, elsewhere to the bot's. purchased_paid_media fires only with a non-empty payload in a non-channel chat and carries from and paid_media_payload, no charge id: there the payload is your order record, and getStarTransactions (transaction_type: "paid_media_payment") gives the transaction id. Paid media can't be copied with copyMessage.
Testing payments
The sources disagree, and no official statement settles it:
| Source | Says | Date |
|---|---|---|
| Stars payments guide | "You can freely test payments in Telegram Stars" in the test environment | page checked 2026-10-30 |
| tdesktop #29956 | A project collaborator, not Telegram: free test Stars were abused and locked | 2025-10-29 |
| tdesktop #30037 | Request for test-environment purchases, closed with a redirect to bugs.telegram.org | 2025-11-23 |
Try the test environment first (separate account and bot, requests to https://api.telegram.org/bot<token>/test/METHOD). If you can't get Stars there, stop and ask the bot's owner. The next step spends real money, so the owner buys the Stars and makes the payment, and an agent never does either. The workaround appears in no documentation: on production, the owner pays a 1-Star invoice to themselves, then the bot calls refundStarPayment on the same charge. It exercises the real path at the cost of a small Stars pack bought once. Use a separate bot, so test orders stay out of real sales.
Verification checklist for that run: successful_payment stored once, a replayed copy of the same update delivers nothing, the refund produces refunded_payment, and access is revoked.
Not verified live
No purchase, refund or subscription was executed for this skill. These remain open:
- A real Stars purchase and refund on production, and a real duplicate
successful_payment. Duplicates are covered by unit tests on synthetic updates only. - Whether test-environment Stars work today.
- Whether a renewal keeps or changes
telegram_payment_charge_id. - Which chat and which
Updatefield carrysuccessful_paymentfor invoices paid in groups, channels and inline. The guide does not say, so accept it from any chat and never filter by chat type.parse_paymentreads every field of typeMessage. A channel post has nofrom, so the helper raisesValueError; dead-letter that update and recover the buyer throughgetStarTransactions. Privacy mode does not hide service messages. - The behavior of a second
refundStarPaymenton one charge. Guard it with your ledger. - How
dateof a renewal ingetStarTransactionsrelates tosubscription_expiration_date. The half-period window in the recovery rules rests on the 30-day period alone. - Which transaction a
refunded_paymentmeans when one charge id covers several periods. It carries no expiry, so the ledger refunds the newest period it holds. - Whether a renewal in
getStarTransactionsalways hassubscription_period. The field is optional. Without it the helper records a one-time row, and a latesuccessful_paymentthen adds a second row. - A repeated refund when renewals share a charge id. The next reconciliation passes the same outgoing transaction again, and
record_refundtakes the newest period not yet refunded, so one refund can withdraw one more period. - The shape of a refund in
getStarTransactions: the helper expectsreceiverof typeuserwithtransaction_typeinvoice_payment, inferred from the field descriptions.
Sources
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |