Telegram Paying Bots

[Niobe Hennigan]

NoteThis article is intended for bot developers and store owners. If you're looking for a general overview of Telegram Payments for physical goods and services, check out the Telegram blog.

You create a bot that offers goods and services to Telegram users. Merchant bots can send specially formatted invoice messages to users, groups or channels. If your bot supports inline mode, users can also send invoices to other chats via the bot, including to one-on-one chats with other users.

Invoice messages feature a photo and description of the product along with a prominent Pay button. Tapping this button opens a special payment interface in the Telegram app. In this interface, users can choose a tip amount (if allowed by the merchant) and enter additional details like shipping info, phone number, or email address.

Telegram does not process payments from users and instead relies on different payment providers around the world. It is the payment providers that handle and store all sensitive information, like credit card details. Neither Telegram nor the bot developers have access to it.

Now you have a merchant bot that can offer goods or services to Telegram users. Let's call it @merchantbot in this document. The first stop is to choose and connect a payment provider, you can find the list of supported providers above.

The user contacts @merchantbot and requests to purchase something. The bot forms an invoice message with a description of the goods or service, amount to be paid, and requested shipping info. There are two ways of creating an invoice:

Use the sendInvoice method to generate an invoice and send it to a chat. The provider_token parameter is where you put the token value that you've obtained earlier via Botfather. It is possible for one merchant bot to use several different tokens for different users or different goods and services.

If @merchantbot supports inline mode, you can use inputInvoiceMessageContent to allow users to share invoices for your goods and services to their one-on-one chats with friends, or to their groups and channels. These invoices will have a Pay button that can be used multiple times.

If a single-chat invoice is sent to the chat with @merchantbot, it can only be paid once. If a single-chat invoice is sent to any other chat, it can be paid many times by many users.

Regardless of whether or not the Pay button is available in an invoice, the merchant bot always has the power to decide whether or not to accept new payments for a particular invoice.

If the max_tip_amount parameter is set to above 0, users can add a tip to their payment. You can use the parameter suggested_tip_amounts to suggest particular amounts that you feel will be relevant for the invoice.

The user specifies shipping information or other info requested by the bot. This could be the user's full name, an email address, a phone number in international format, or a full postal address for delivery.

If a shipping address was requested and you included the parameter is_flexible, the Bot API will send an Update with a shipping_query field to the bot. The bot must respond using answerShippingQuery either with a list of possible delivery options and the relevant delivery prices, or with an error (for example, if delivery to the specified address is not possible).

The user enters their payment information and presses the final pay button. At this moment the Bot API sends an Update with the field pre_checkout_query to the bot that contains all the available information about the order. Your bot must reply using answerPrecheckoutQuery within 10 seconds after receiving this update or the transaction is canceled.

The bot may return an error if it can't process the order for any reason. We highly recommend specifying a reason for failure to complete the order in human readable form (e.g. "Sorry, we're all out of rubber ducks! Would you be interested in a cast iron bear instead?"). Telegram will display this reason to the user.

Warning: It is critical to make sure your bot only accepts multiple payments when the order can be processed correctly. This is especially important if you are using multi-chat, inline or single-chat, multi-use invoices.

In case the bot confirms the order, Telegram requests the payment provider to complete the transaction. If the payment information was entered correctly and the payment goes through, the API will send a receipt message of the type successful_payment from the user. Once your bot receives this message, it should proceed with delivering the goods or services purchased by the user.

Once you've tested everything and confirmed that your payments implementation works, you're ready to switch to LIVE MODE. To do this, go to BotFather > /mybots > select @merchantbot > Bot Settings / Payments and enable Stripe LIVE MODE. You will get a token that has the string :LIVE: in the middle, e.g. 123:LIVE:XXXX. Do not give this token to any third parties!

Telegram does not charge any commission for using the Payments API. Note though, that most payment providers will have their own commissions. For example, Stripe in the US charges 2.9% + 30 per successful card charge (see the Stripe website for more details on pricing).

Telegram acts as a messenger between the paying user, the bot developer, and their chosen payment system. The user sends their credit card details directly to the payment system. Then the payment system's response and the shipping details entered by the user are passed to the bot developer so that they can process the order.

The minimum and maximum amounts for each of the currencies roughly correspond to the limit of US$ 1-10000. The amount must be expressed in 12 digits or less, so the maximum value will be correspondingly lower for some lower-value currencies. Note that for each currency except USD these limits depend on exchange rates and may change over time (plan ahead for this when you implement limits in your code).

UPD 2024: Bots can now sell digital goods and services. For more details, see Telegram Stars and the updated Payments Documentation for digital and physical products.

If you have Telegram 4.0 (or newer) installed, you can order goods or services from bots that offer them. These bots may now add a Pay button to their messages. When you tap Pay, you'll be asked to fill in your credit card and shipping information and confirm the payment. Then you get what you paid for. Voila!

If your account is protected by 2-Step Verification, you can save your card for future purchases. If you do that, ordering stuff from bots will only take two taps. Bot Payments also support Apple Pay for a completely frictionless experience.

At launch, most of the payments were handled by Stripe, but Telegram Bot Payments are a platform for payment providers all over the world. When accepting a payment from a user, the bot developer can choose between all available payment providers, selecting the one already used by the buyer or the one with the lowest commission.

Telegram acts as a messenger (pun intended) between the paying user, the bot developer, and their chosen payment system. The user sends their credit card details directly to the payment system. Then the payment system's response and the shipping details entered by the user are passed to the bot developer so that they can process the order.

Telegram hosts a variety of bots for numerous tasks including gaming, news reading, creating new Telegram bots, and facilitating Telegram payments. In 2017, Telegram rolled out a Payments API, which empowered developers to craft Payment Bots for handling Telegram payments.

Despite Telegram's Payment API limitations, the app serves as the ultimate platform for launching mobile-optimized, subscription-based ventures. This opens up avenues for creatives and entrepreneurs across the globe to generate income and attain financial independence.

If you're thinking about setting up your own Telegram payment system, there are some things to consider. Understanding the difference between a payment bot and a subscription bot, learning how to accept Telegram payments through the app, and knowing the available payment services will help you make the right choice for your business.

A Telegram payment bot is basically any bot that uses the Telegram, or a custom Payments API, for accepting payments through Telegram groups and channels. Each of these bots can be different and have as many features as a developer can enable for them.

Payment bots are added to your private group or channel, so members can interact with them and make payments. The best example of a payment bot is the ShopBot. It resides in the Demo Store, a mock Telegram channel where imaginary goods are sold.

Having a payment bot, like ShopBot, will allow you to sell goods or services on an online catalog. The payment bot creates invoices that include a picture, text, and a payment button and can be sent to groups, channels, and single chats.

Building this kind of bot requires a certain level of technical knowledge or the skills of a competent developer. Telegram has a list of supported region-locked payment providers, including platforms like Stripe, ECOMMPAY, and Global Pay UZ, with their own bots to help you set up your integration.

Subscription bots go beyond the limits of the Payments API and what payment bots can do, allowing users to receive recurring payments from their customers. The first Telegram subscription bot was the InviteMember bot. Among many things, this bot will help you create a membership-based business made up of private groups and channels and accept a wide variety of payment options for paying for your subscription plans.

3a8082e126