Skip to main content

Telegram Payments, Stars and Gifts

Sell with the bot you connected to the profile, following Telegram's payments for digital goods (Telegram Stars) and payments for physical goods.

  • Authentication: API Key — Authorization: Apikey <YOUR_API_KEY>
  • Every endpoint takes the profile in user (query string or JSON body).
Whose money is it?

All payments go to your bot, never to Upload-Post. Buyers pay your bot; refunds, gifts and Telegram Premium gifts are paid from your bot's Stars balance. Upload-Post does not charge any fee. Digital goods and services must be sold in Telegram Stars (currency XTR); physical goods use a payment provider token from @BotFather (Bot Settings > Payments).

Operations that move Stars are explicit

Refunds, subscription changes and anything that spends the bot's Stars require "confirm": true. Everything that spends the bot's Stars (gifts, Telegram Premium, allow_paid_broadcast, a priced suggested post) also requires an idempotency_key (up to 128 characters, e.g. your order id) and a ceiling: max_star_count for gifts (checked against Telegram's current price before sending), the exact star_count for Premium, suggested_post_max_amount for a priced suggested post.

These requests are never retried automatically. If Telegram does not confirm the result (timeout, dropped connection or a 5xx from Telegram) the API returns 504 telegram_outcome_unknown: check the Stars transactions before trying again, with a new key. Repeating a request with the same idempotency_key returns the first answer instead of calling Telegram twice; if the first attempt provably sent nothing (Telegram unreachable, rate limit, a check that failed before sending), the same key can be used again.

Spending the bot's Stars is turned off on Upload-Post until further notice: those requests answer 503 telegram_stars_spend_disabled and nothing is sent.

How a sale works​

  1. Send an invoice to a chat, or create an invoice link.
  2. The buyer presses Pay. Telegram asks your bot to confirm (pre_checkout_query) and cancels the checkout if nobody answers within 10 seconds. Upload-Post can answer for you from a stored rule (see Automatic pre-checkout answers); this needs update receiving enabled for the bot, which is not generally available yet.
  3. Deliver the goods only after the successful_payment message arrives: answering the pre-checkout query does not guarantee the payment. Keep its telegram_payment_charge_id for refunds.

Send an invoice​

  • Method: POST
  • Endpoint: /api/uploadposts/telegram/invoices

Sends sendInvoice to the profile's connected chat, or to chat_id (a chat the bot can write to, e.g. a user who started it).

FieldTypeRequiredDescription
userstringYesProfile username.
titlestringYesProduct name, 1-32 characters.
descriptionstringYes1-255 characters.
payloadstringYesYour own reference, 1-128 bytes, not shown to the buyer.
currencystringNoXTR (Telegram Stars, default) or a 3-letter ISO 4217 code.
pricesarrayYes[{"label": "...", "amount": 50}] in the smallest unit (Stars for XTR, cents for EUR). Exactly one item for Stars.
provider_tokenstringFor real currenciesFrom @BotFather. Must be empty for Stars. Never stored.
chat_idinteger or @usernameNoTarget chat; defaults to the connected chat.
max_tip_amount, suggested_tip_amountsinteger, arrayNoTips (not for Stars).
start_parameterstringNoForwarded copies show a deep link to the bot instead of a Pay button.
photo_url, photo_size, photo_width, photo_heightNoProduct photo.
need_name, need_phone_number, need_email, need_shipping_address, send_phone_number_to_provider, send_email_to_provider, is_flexiblebooleanNoPhysical goods only (ignored for Stars).
provider_dataobject or stringNoPassed to the payment provider.
message_thread_id, direct_messages_topic_idintegerNoForum topic / channel direct messages topic.
disable_notification, protect_contentbooleanNo
allow_paid_broadcastbooleanNoUp to 1000 msg/s for 0.1 Stars per message from the bot's balance. Requires confirm: true and idempotency_key.
suggested_post_parametersobjectNoSuggestedPostParameters (direct messages chats). With a price (XTR 5-100000 or TON in nanograms) the bot pays it when the post is approved: requires suggested_post_max_amount (same unit), confirm: true and idempotency_key.
message_effect_id, reply_parameters, reply_markupNoOfficial Bot API objects. The first button of reply_markup must be a Pay button.
curl -X POST 'https://api.upload-post.com/api/uploadposts/telegram/invoices' \
-H 'Authorization: Apikey YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"user": "my-shop", "title": "PDF guide", "description": "Complete guide",
"payload": "order-1", "currency": "XTR", "prices": [{"label": "Guide", "amount": 50}]}'
{ "success": true, "message_id": 77, "post_id": 77, "chat_id": -1001234567890,
"url": "https://t.me/c/1234567890/77", "invoice": { "currency": "XTR", "total_amount": 50 } }
  • Method: POST
  • Endpoint: /api/uploadposts/telegram/invoice-links

Same fields as above except the chat-related ones, plus:

FieldTypeDescription
subscription_periodinteger2592000 (30 days, the only value Telegram accepts) turns the link into a monthly Stars subscription. Stars only, price at most 10000 Stars.
business_connection_idstringCreate the link on behalf of a connected business account (Stars only).

Returns {"success": true, "invoice_link": "https://t.me/$..."}.

Refund a Stars payment​

  • Method: POST
  • Endpoint: /api/uploadposts/telegram/stars/refund
FieldTypeRequiredDescription
user_idintegerYesTelegram id of the buyer.
telegram_payment_charge_idstringYesFrom successful_payment, or the Stars transaction id.
confirmbooleanYesMust be true. Refunds cannot be undone.
idempotency_keystringNoSee above (a charge can only be refunded once anyway).

Returns {"success": true, "operation_id": "...", ...}. A payment refunded before answers 409 telegram_charge_already_refunded.

Cancel or re-enable a subscription​

  • Method: POST
  • Endpoint: /api/uploadposts/telegram/stars/subscription

editUserStarSubscription: user_id, telegram_payment_charge_id (of the subscription), is_canceled (true stops the renewal at the end of the paid period; false lets the user re-enable a subscription the bot canceled) and confirm: true.

Gifts​

MethodEndpointWhat it does
GET/api/uploadposts/telegram/giftsGifts the bot can send, with their price in Stars (getAvailableGifts). Cached 10 minutes.
POST/api/uploadposts/telegram/giftsSend a gift paid from the bot's Stars (sendGift).
POST/api/uploadposts/telegram/gifts/premiumGift Telegram Premium (giftPremiumSubscription).
GET/api/uploadposts/telegram/gifts/ownedGifts owned by a user (user_id) or a chat (chat_id, default the connected chat).
GET/api/uploadposts/telegram/gifts/unique?name=A unique gift by name (getUniqueGift).

Send a gift: user_id or chat_id (a channel), gift_id, max_star_count (required), idempotency_key (required), confirm: true, and optionally pay_for_upgrade, text (0-128 characters), text_parse_mode or text_entities. Limited gifts can't be sent to channels. If the price (plus the upgrade when pay_for_upgrade) is above max_star_count, nothing is sent and the answer is 400 telegram_price_above_limit with the current star_count.

Gift Premium: user_id, month_count (3, 6 or 12), star_count (exactly 1000, 1500 or 2500), idempotency_key, confirm: true, optional text.

Owned gifts filters: exclude_unlimited, exclude_limited_upgradable, exclude_limited_non_upgradable, exclude_from_blockchain, exclude_unique, sort_by_price; for chats also exclude_unsaved and exclude_saved; pagination with offset (the next_offset of the previous page) and limit (1-100).

Automatic pre-checkout answers​

  • Endpoint: GET / PUT /api/uploadposts/telegram/payments/settings

Telegram gives your bot 10 seconds to confirm each checkout. Store a rule and Upload-Post answers at once (requires update receiving enabled for the bot, which is not generally available yet: until then you can save rules, but no payment query reaches Upload-Post to answer). Saving a rule that answers (approve, reject or shipping: static) requires "confirm": true; turning everything off does not.

FieldDescription
pre_checkoutoff (default: Upload-Post does not answer; the query is passed to you to answer; switching to off also clears max_total_amount unless you send it), approve (approve the orders that pass the filters below), reject (reject every payment of the bot, with error_message).
max_total_amountRequired for approve. Maximum order total per currency, in the smallest unit: {"XTR": 500, "EUR": 2000}. Orders in a currency not listed, or above its amount, are rejected.
only_upload_post_invoicesDefault true: only orders for invoices or invoice links created through Upload-Post for this bot are approved, in the same currency and never cheaper than created (if you reuse a payload with several prices, each price is remembered). This is a safeguard, not a cryptographic proof: anyone holding your bot token can create invoices with the same payload. Set false to also approve invoices created elsewhere (your own code, other integrations), still within max_total_amount.
allowed_payload_prefixesOptional: only orders whose payload starts with one of these are approved.
error_messageShown to the buyer by Telegram when an order is rejected (up to 255 characters).
shippingoff or static: answer shipping queries with shipping_options (up to 20 Telegram ShippingOption: id, title, up to 10 prices), limited to shipping_countries (ISO country codes) if given.

The answer includes warnings (e.g. when reject blocks all sales) and scope:

  • Rules belong to the bot in your account: every profile of the account that uses the same bot shares them (scope.shared_by_profiles).
  • When you save rules, scope.connected_in_another_account tells you if the same bot is also used in another Upload-Post account: Telegram sends each payment query to one receiver only, so the rules apply only in the account that receives the bot's updates.

Every automatic answer is sent in a single attempt within Telegram's deadline. If Telegram could not be reached and there is still time, the query is passed to you to answer. If the answer failed or came too late, it is recorded and listed by GET /api/uploadposts/telegram/payments/unanswered?user=<profile>[&limit=50] (last 30 days: kind, state failed/unknown/expired, error_code, query_id, currency, total_amount, buyer_id). When automatic answers are paused on Upload-Post, payment queries are passed to you to answer.

warning

With approve, every order that passes the filters is accepted automatically, including repeat payments of multi-use invoices. Only use it when you can always deliver; deliver after successful_payment.

Errors​

Same shape and codes as Telegram chat data, plus:

Statuserror_codeMeaning
400confirmation_requiredRepeat with "confirm": true.
400idempotency_key_requiredSpending requests need an idempotency_key.
400telegram_price_above_limitThe gift (or suggested post) costs more than your ceiling; nothing was sent.
402telegram_insufficient_starsThe bot does not have enough Stars.
404telegram_gift_not_foundThe gift is not available (sold out or removed).
409telegram_charge_already_refundedThe payment was already refunded.
409idempotency_key_reusedThe key was used for a different request.
409 / 504telegram_outcome_unknownTelegram did not confirm the result (timeout, dropped connection or a Telegram 5xx). Check the Stars transactions before retrying with a new key.
503telegram_payments_disabled, telegram_stars_spend_disabledTemporarily disabled; nothing was sent to Telegram.