Payments in Telegram require more than adding a button and connecting a service. You need to define what is being sold, the permitted payment flow, the order confirmation rules and the refund process.
Before development, check the entire path: product selection, amount calculation, payment, receiving the result and contacting support. Agree on the payment method alongside the product type and market.
Start with what the customer is buying
Telegram distinguishes payments for digital goods and services from payments for physical goods and services.
Telegram Stars are mandatory for selling digital goods and services inside bots and Mini Apps. Having your own website with another payment method does not remove this rule for sales inside Telegram. Digital payment rules.
For physical goods and services, Telegram provides a flow using third-party payment providers. Telegram passes payment data into the relevant process, while the service terms depend on the selected provider. Telegram Payments documentation.
Hypothetical examples: ordering a physical product for delivery and buying access to digital material in Telegram require different flows. For a mixed offer, separately identify what is being paid for and where the result is delivered. Calling something a “service” does not, by itself, determine the payment method.
If the offer's classification is ambiguous, clarify the platform's and provider's requirements before designing the solution. Do not plan card payments as a universal option for every sale.
Prepare a payment scenario brief
For each order type, record:
- what is sold and how the result is delivered;
- the seller's country and target markets;
- the currency or Stars, amount breakdown and applicable charges;
- the available provider and account requirements;
- whether delivery, contact details or appointment booking are needed;
- when stock or a place is reserved;
- the events confirming payment and order fulfillment;
- cancellation, refund and support rules.
For a third-party provider, check whether your company can sign up, supported countries and payment methods, fees, payout timing and dispute handling. These terms are compared in the article on choosing a payment provider.
For Stars, assess reward conditions and the availability of the relevant process for your business separately. What a user pays to buy Stars does not automatically equal the seller's payout: Telegram describes these as different values. Platform terms.
Separate invoicing, payment and order fulfillment
Agree on the states: order created, awaiting payment, paid, awaiting fulfillment, fulfilled, canceled or refunded. Track payment separately from delivery of the result.
For a standard Bot API invoice, the pre-checkout step requires the bot to reply within 10 seconds. At this point, confirm that the order can still be fulfilled and its terms are current. Approving this check does not confirm payment. Payment procedure.
Set the “Paid” status after a verified server-side successful payment event. For the built-in Bot API flow, this is successful_payment. Retain the link between the payment and order, and the payment identifier. SuccessfulPayment documentation.
Closing a payment window or a customer's message saying “I paid” must not, by itself, unlock a product. A repeated event must not fulfill the same order again, and a new purchase must not be blocked as a duplicate.
Check the Mini App and the server side
In a Mini App, user data and the amount must not be trusted simply because they came from the interface. The server should verify the user, order and calculation according to your rules.
Telegram requires initData validation before server-side use and warns that initDataUnsafe must not be trusted. Mini Apps documentation.
Define how the order reaches the CRM, inventory system or access system. If payment is already confirmed but an integration is temporarily unavailable, preserve the order for processing again. Show the customer the real state and alert the responsible person to the problem.
Prepare refunds and support
Before paying, customers should understand what they will receive, on what terms and where to ask for help. Agree on terms, seller information and the documents needed for the selected markets with the responsible specialists.
For digital purchases, Telegram requires inquiries through the /paysupport command to be handled. Assign a staff member to deal with these requests. Payment support requirements.
The Bot API includes refundStarPayment for refunding a successful Stars payment. For other methods, the refund process depends on the provider integration. Check partial refund capabilities separately; do not promise them by default. Stars refund method.
Describe what happens to access, stock reservations and CRM status after a refund. Separately plan for cases where the money has been refunded but another system failed to update.
Checklist before launch
- The sale type and permitted payment method are confirmed.
- The seller's account and required connections are ready.
- Price, currency, delivery and the total amount are shown before payment.
- Successful, declined and canceled payments are handled.
- Repeated button presses and repeated event delivery have been checked.
- Changes in availability or terms before payment do not create an order that cannot be fulfilled.
- A paid order is preserved if the CRM or access delivery fails.
- Refunds are reflected in the order and connected systems.
- Support is available, and notifications and terms are localized.
- The agreed Telegram applications, devices and recovery procedure have been checked.
Include acceptance conditions in the bot specification. Budget for order statuses, integrations, error handling and support as well as the payment screen; the scope is discussed in the article on Telegram bot costs.
To discuss Telegram bot and Mini App development, prepare payment scenario briefs and information about the systems you use. The commercial proposal provides a basis for agreeing on development scope. Check the specific payment method, provider availability and current Telegram rules before implementation.