Skip to content

Accepting Stars or delivering them

Telegram's Bot Payments API lets your bot accept Stars. Delivering Stars to a user's account is a different job. Which one you need, and why.

"Telegram Stars API" names two different jobs. Telegram's own Bot Payments API lets a bot accept Stars from its users, as payment for digital goods and services. The Nasfam Business API delivers Stars to a Telegram account you name, paid from your prepaid balance. Most integrations need one of the two; some need both.

Nasfam Business is an independent service and is not affiliated with Telegram.

The two jobs, side by side

Accepting Stars (Telegram Bot Payments)Delivering Stars (this API)
Who paysA user pays your bot, inside Telegram.You pay, from your prepaid balance.
Where the Stars goTo your bot.To the Telegram account at the username you send.
How the price is writtenIn XTR, the currency code Telegram uses for Stars.In USD, held by a quote for up to 60 seconds.
What you callA Bot API invoice, with its currency set to XTR.POST /recipient-lookups, POST /quotes and POST /orders.
How you learn the resultA message in your bot's updates once the payment succeeds.A signed event when the order ends, or GET /orders/{id}.
Typical useSelling a digital item or a feature inside your bot.A reward, a prize or a purchase in your own app, bot or store.

Telegram documents the first job in Bot Payments for digital goods and services. The second is Telegram Stars in these pages.

Which one you need

  • Your users pay you, in Telegram, for something digital: Bot Payments. Nasfam Business plays no part in it.
  • You want Stars to arrive in someone's Telegram account (a reward, a giveaway prize, an item your customer bought from you): delivery. Look up the username, have your customer confirm the account, quote, order, and follow the order to its end.
  • Both: a bot can take payments in Stars and also order deliveries through this API. They are separate integrations, with separate money: what your bot earns in Stars never funds a delivery order.

Can a bot send Stars to a user?

Telegram's Bot Payments pages describe how a bot accepts Stars and how it refunds a payment it received (refundStarPayment). They do not describe sending Stars from a bot to a username of your choosing. To put Stars into an account you name, order a delivery: the Bot API reference is where to check what a bot itself can do.

A delivery is not a payment from the recipient. They do not need to use your bot. Your customer confirms the account before you order, from the name and photo the lookup returns. See Recipient lookup.

What XTR is

XTR is the currency code Telegram uses for Stars in the Bot Payments API: an invoice for digital goods is priced in it. This API never uses it. A delivery is a quantity of Stars, within the bounds GET /products returns, and its price is in USD, fixed by a quote before anything is spent. See Pricing and costs.

And Telegram Premium

The same split holds for Premium. Telegram's Bot API reference describes gifting Premium from a bot, paid in the bot's own Stars. This API delivers Premium for 3, 6 or 12 months to the account at a username, paid from your balance in USD: see Telegram Premium.