A practical guide to payment rules, checkout events, subscriptions, and fulfilment.

Telegram Stars vs External Payments: Which Payment Flow Fits Your Product?

A practical guide to payment rules, checkout events, subscriptions, and fulfilment.

A Telegram bot selling an ebook and one selling a printed book may have similar interfaces. Their payment integrations need to follow different rules.

When comparing Telegram Stars vs external payments, start with the product and purchase flow. These determine which Telegram payment options apply before you evaluate integration effort and ongoing support.

The examples below are illustrative. The rules and API details were checked against official documentation on October 8, 2026.

1. Classify the product before choosing a provider

Telegram requires Stars for digital goods and services sold inside Telegram apps through bots or mini apps. Its developer terms establish that requirement.

For physical goods and services, Telegram supports third-party payment providers through its Bot Payments API.

Define what the customer receives in the product specification. “Membership” alone is too vague: it could describe access to digital content or a physical service.

If the classification is unclear, resolve it against the applicable rules before building checkout. An integration that accepts a transaction does not establish that the product is eligible for that payment method.

2. Understand the two meanings of external payments

“External” can describe the processor or the checkout location.

For physical goods, a third-party PSP—payment service provider—can process a purchase through Telegram's invoice interface. The customer does not necessarily need to leave Telegram. The provider handles payment information and applies its own availability, onboarding, and transaction requirements.

An independent website checkout is a different purchase flow. It needs its own assessment, including how a connected bot offers or delivers the product.

Having a website does not exempt digital sales inside bots or mini apps from Stars. A checkout link alone does not establish an exception. See the website question in Telegram's payment FAQ.

The practical differences are:

Aspect	Telegram Stars	External payment provider
Product fit	Digital goods and services sold inside Telegram bots or mini apps	Physical goods and services; assess independent website flows separately
Checkout	A Telegram Stars invoice	A Telegram invoice with a supported PSP, or a website checkout for a permitted purchase flow
Payment units	XTR, measured in Stars	Currencies and payment methods supported by the provider
Confirmation	Telegram's successful_payment update	successful_payment for Telegram invoices; provider payment events for website checkout
Recurring billing	30-day subscriptions through the relevant Stars API methods	The provider's supported subscription model
Seller proceeds	Developer rewards under Telegram's terms, subject to withdrawal availability	Provider settlement rules, merchant eligibility, and fees
Refunds	Telegram's Stars refund API	The provider's refund process

These routes serve different purchase flows. Check a monetization platform's documented flow for your actual offer, alongside its list of payment integrations.

3. Create a Stars invoice with the correct units

For a one-time Telegram Stars payment, an illustrative sendInvoice request body looks like this:

{
  "chat_id": 123456789,
  "title": "Template pack",
  "description": "One downloadable template pack",
  "payload": "order_demo_001",
  "provider_token": "",
  "currency": "XTR",
  "prices": [
    {
      "label": "Template pack",
      "amount": 100
    }
  ]
}

Replace the example chat and order identifiers. Here, amount: 100 means 100 Stars. Stars invoices use XTR, an empty provider token, and exactly one price item.

Keep the order's expected buyer, product, amount, and currency on your server. Use the payload to find that record during checkout.

Source: Bot API: sendInvoice.

4. Confirm payment before delivering

If you receive Telegram updates through webhooks, configure secret_token in setWebhook and verify the X-Telegram-Bot-Api-Secret-Token header before trusting incoming updates.

Telegram's Stars checkout flow has two distinct stages:

• pre_checkout_query: validate the order and respond through answerPreCheckoutQuery within 10 seconds.
• successful_payment: the payment confirmation that allows fulfilment to begin.

Approving pre-checkout is permission to proceed. It is not proof of payment.

A practical implementation pattern is to:

1. Validate the buyer, order, amount, currency, and availability during pre-checkout.
2. Match the confirmed payment to the order.
3. Persist its telegram_payment_charge_id.
4. Queue delivery or the relevant access change.

A uniqueness constraint on the payment charge ID can prevent duplicate payment records. With an outbox, one database transaction records both the payment and a fulfilment task; a worker then performs delivery. This closes the gap where a process could crash after saving payment but before scheduling fulfilment.

Outbox workers can retry tasks, so they do not guarantee exactly-once delivery. Keep the business action idempotent: the same charge must not create a second entitlement or extend the same paid period twice. Account for possible duplicate notifications. See the transactional outbox pattern.

Keep payment and delivery status separate. If payment succeeds but file delivery fails, the order remains paid with fulfilment pending. Retry delivery and surface the failure for support.

5. Separate subscription billing from access rules

Stars support recurring payments. For bot subscriptions, createInvoiceLink accepts subscription_period; the documented value is currently 2592000 seconds, or 30 days.

For a custom entitlement—permission to use a feature or service—track subscription_expiration_date from the successful payment. Cancellation of future renewal should preserve the current paid period, as documented by editUserStarSubscription.

Telegram also supports native paid channel invite links. The Bot API method createChatSubscriptionInviteLink targets channel chats and requires can_invite_users administrator rights. Plan group access separately.

Write the access policy before implementation:

• Which feature or chat does the purchase cover?
• When does access expire?
• What happens after an unsuccessful renewal?
• How does a refund affect that specific purchase?

Keep each entitlement tied to its purchase. Refunding one order should not erase a customer's unrelated valid purchases.

6. Handle external payment events around a concrete order

Consider a website selling a monthly box of printed books. The payment provider handles recurring billing, and a Telegram bot sends shipping updates. This example concerns a physical product; provider availability and merchant requirements still need checking.

Stripe's webhook documentation describes signature verification using the raw request body, duplicate delivery, and events arriving out of order. For such a flow:

• Verify the webhook signature before processing the event.
• Track processed event IDs to recognise repeated deliveries.
• Protect the business action with a stable identifier, such as the paid invoice ID for its shipment task. Separate Event objects can describe the same underlying action.
• Retrieve the relevant current resource state when event ordering matters.

Stripe's subscription webhook guide covers events such as invoice.paid and invoice.payment_failed. In the book-box example, processing the same paid invoice twice should still schedule only one shipment. When storing identifiers, distinguish provider accounts and test/live environments where needed.

An unsuccessful renewal needs a defined response: notify the customer, follow the billing retry policy, and apply the published service terms. This follow-up process is commonly called dunning.

Also plan reconciliation: periodically compare local payment and order records with the payment system's authoritative records. This can reveal missed updates and unfinished fulfilment jobs. The same principle applies to custom access records where the purchase legitimately grants access.

7. Model the proceeds you can actually receive

For Stars, distinguish the buyer's acquisition cost from the developer's rewards.

The developer terms currently state a reward equivalent of $0.013 per Star. At that rate, 1,000 Stars correspond to $13 in rewards before applicable adjustments. That is not the buyer's purchase price or a guaranteed bank payout.

The terms also describe:

• Up to 21 days before received Stars become available for rewards or advertising credits.
• Rewards processing through Fragment, with availability restrictions.
• A 15% fee on Stars purchases while topics in private bot chats are enabled.

Account for the configuration you actually use. Prices paid to acquire Stars also vary with applicable taxes and fees, as noted in Telegram's pricing documentation.

For an external provider, inspect merchant country eligibility, KYC requirements, supported payment methods, processing and billing fees, settlement currency, payout schedule, and refund costs.

KYC means Know Your Customer: the verification required by the relevant financial provider. Receiving a Telegram Stars payment and qualifying to receive developer rewards are separate steps.

Model expected proceeds using your order volume and billing period. Include operating costs, support, and failed fulfilment work rather than relying on a headline transaction fee.

8. Test the failures customers will notice

Before launch, exercise these cases:

• A webhook arrives with an invalid authentication token or signature.
• The same payment confirmation is processed twice.
• Two provider events refer to the same paid invoice.
• Payment is confirmed, but delivery fails.
• Renewal is canceled before the paid period ends.
• A refund affects one of several purchases.
• A missed event is discovered during reconciliation.

Telegram provides a test environment for Stars payments. For an external provider, use its supported test tools.

Provide a usable purchase-support route. Telegram requires digital-payment bots to respond to /paysupport; refundStarPayment supports refunding a successful Stars payment.

Choose the flow around the offer

Choose the payment flow your product and Telegram integration permit. Then make every confirmed payment traceable to a specific order or paid period, with a clear delivery and refund status. Authenticate incoming events, handle retries, and preserve the customer's valid purchases when changing access.

That gives you a practical launch criterion: customers receive what they paid for, while duplicate events and delivery failures remain manageable.

Which part of a Telegram payment integration has been hardest for you to get right: confirmation, renewal, or access changes?

Disclosure: This article was drafted with generative AI assistance. The request example is illustrative and was not executed against a live bot.