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).
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).
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
- Send an invoice to a chat, or create an invoice link.
- 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. - Deliver the goods only after the
successful_paymentmessage arrives: answering the pre-checkout query does not guarantee the payment. Keep itstelegram_payment_charge_idfor 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).
| Field | Type | Required | Description |
|---|---|---|---|
user | string | Yes | Profile username. |
title | string | Yes | Product name, 1-32 characters. |
description | string | Yes | 1-255 characters. |
payload | string | Yes | Your own reference, 1-128 bytes, not shown to the buyer. |
currency | string | No | XTR (Telegram Stars, default) or a 3-letter ISO 4217 code. |
prices | array | Yes | [{"label": "...", "amount": 50}] in the smallest unit (Stars for XTR, cents for EUR). Exactly one item for Stars. |
provider_token | string | For real currencies | From @BotFather. Must be empty for Stars. Never stored. |
chat_id | integer or @username | No | Target chat; defaults to the connected chat. |
max_tip_amount, suggested_tip_amounts | integer, array | No | Tips (not for Stars). |
start_parameter | string | No | Forwarded copies show a deep link to the bot instead of a Pay button. |
photo_url, photo_size, photo_width, photo_height | No | Product photo. | |
need_name, need_phone_number, need_email, need_shipping_address, send_phone_number_to_provider, send_email_to_provider, is_flexible | boolean | No | Physical goods only (ignored for Stars). |
provider_data | object or string | No | Passed to the payment provider. |
message_thread_id, direct_messages_topic_id | integer | No | Forum topic / channel direct messages topic. |
disable_notification, protect_content | boolean | No | |
allow_paid_broadcast | boolean | No | Up to 1000 msg/s for 0.1 Stars per message from the bot's balance. Requires confirm: true and idempotency_key. |
suggested_post_parameters | object | No | SuggestedPostParameters (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_markup | No | Official 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 } }
Create an invoice link (and Stars subscriptions)
- Method:
POST - Endpoint:
/api/uploadposts/telegram/invoice-links
Same fields as above except the chat-related ones, plus:
| Field | Type | Description |
|---|---|---|
subscription_period | integer | 2592000 (30 days, the only value Telegram accepts) turns the link into a monthly Stars subscription. Stars only, price at most 10000 Stars. |
business_connection_id | string | Create 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
| Field | Type | Required | Description |
|---|---|---|---|
user_id | integer | Yes | Telegram id of the buyer. |
telegram_payment_charge_id | string | Yes | From successful_payment, or the Stars transaction id. |
confirm | boolean | Yes | Must be true. Refunds cannot be undone. |
idempotency_key | string | No | See 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
| Method | Endpoint | What it does |
|---|---|---|
GET | /api/uploadposts/telegram/gifts | Gifts the bot can send, with their price in Stars (getAvailableGifts). Cached 10 minutes. |
POST | /api/uploadposts/telegram/gifts | Send a gift paid from the bot's Stars (sendGift). |
POST | /api/uploadposts/telegram/gifts/premium | Gift Telegram Premium (giftPremiumSubscription). |
GET | /api/uploadposts/telegram/gifts/owned | Gifts 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.
| Field | Description |
|---|---|
pre_checkout | off (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_amount | Required 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_invoices | Default 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_prefixes | Optional: only orders whose payload starts with one of these are approved. |
error_message | Shown to the buyer by Telegram when an order is rejected (up to 255 characters). |
shipping | off 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_accounttells 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.
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:
| Status | error_code | Meaning |
|---|---|---|
| 400 | confirmation_required | Repeat with "confirm": true. |
| 400 | idempotency_key_required | Spending requests need an idempotency_key. |
| 400 | telegram_price_above_limit | The gift (or suggested post) costs more than your ceiling; nothing was sent. |
| 402 | telegram_insufficient_stars | The bot does not have enough Stars. |
| 404 | telegram_gift_not_found | The gift is not available (sold out or removed). |
| 409 | telegram_charge_already_refunded | The payment was already refunded. |
| 409 | idempotency_key_reused | The key was used for a different request. |
| 409 / 504 | telegram_outcome_unknown | Telegram did not confirm the result (timeout, dropped connection or a Telegram 5xx). Check the Stars transactions before retrying with a new key. |
| 503 | telegram_payments_disabled, telegram_stars_spend_disabled | Temporarily disabled; nothing was sent to Telegram. |