Bot Payments API

You can accept payments from Telegram users via Telegram Bots.

Note: This article is intended for bot developers. If you're looking for a general overview of Telegram Payments, check out the Telegram blog.

If you are new to Telegram bots and would like to learn how to create and set up a bot, please consult our Introduction to Bots and Bot FAQ.

Introducing Payments

Telegram bots can accept payments for goods and services from users as of Bot API v.3.0. Users will need Telegram v.4.0 or higher to pay for your goods and services.

How does this work?

From the user's perspective the new payments system is completely seamless. Merchant bots can send specially formatted invoice messages to users. Such 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 new interface, users are prompted for additional details like shipping info, phone number, or email address.

Once they've entered all the necessary info, it is forwarded to the merchant bot. The bot can offer several shipping options for physical goods based on the address. When ready, users can enter their credit card info or choose one of their saved cards — and pay for the product. Telegram for iOS also supports Apple Pay. Once the transaction is done, the merchant bot sends a receipt message that contains payment details along with shipping and delivery information.


How do you process payments?

Telegram does not process payments from users and instead relies on different payment providers around the world. The first provider we connected to the Bot API for this launch is Stripe. 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.

In the next few days, payments will become available to developers in India via Razorpay, in Nigeria, Kenya, Ghana, South Africa, and Uganda via Flutterwave, and in over 190 countries via Paymentwall. Yandex.Money for Russia and Payme for Uzbekistan will be joining the club a little later. More providers to be announced in the coming weeks.

How do I join as a payment provider?

If you work for a company that provides services similar to standalone accounts in Stripe Connect, please let us know via @BotSupport (kindly include the hashtag #paymentsprovider in your message).

How much do you charge?

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).

What can my bot sell?

Telegram does not impose any limits on what products or services your bot can offer. But please note that you must comply with the rules of the payments provider you choose in our system. E.g., Stripe has a special page for prohibited businesses – you may want to consult that one before you start selling harvested organs.

Special Note: Due to Apple's limitations, bot developers are currently not allowed to accept payments for digital goods and virtual services from iOS users.

How are disputes handled?

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.

Since Telegram doesn‘t process the payments, we don’t store and can‘t access any sensitive data. Due to this structure, it is impossible for Telegram to handle complaints or cashbacks – any disputed payments are the responsibility of the bot developers, payment providers, and banks that participated in the exchange.

See also: Telegram Privacy Policy

The Payments API

Now let‘s look at payments via Telegram’s Bot API in more detail. To start accepting payments, you need a Telegram bot, obviously. Have a chat with BotFather to create a bot if you haven't got one already.

Connecting Payments

Now you have a merchant bot that wants to offer goods or services to Telegram users. Let's call it @merchantbot in this document. First stop is to choose and connect a payment provider. At the moment, you can use Stripe for bot payments. We will be connecting more providers in the coming months, so watch out for announcements on the @BotNews channel.

Getting a Token

Use the /mybots command in the chat with BotFather and choose the @merchantbot that will be offering goods or services. Go to Bot Settings > Payments. Choose a provider, and you will be redirected to the relevant bot. Enter the required details so that the payments provider is connected successfully, go back to the chat with Botfather. The message will now show available providers. Each will have a name, a token, and the date the provider was connected. You will use the token when working with the Bot API.

Testing Payments: the ‘Stripe TEST MODE’ Provider

While you‘re still developing and testing payments for your bot, use the “Stripe TEST MODE” provider. When in this mode, you can make payments without actually billing any accounts. Real cards can’t be used in test mode, but you can use test cards like 4242 4242 4242 4242 (full list here). You can switch between test mode and live mode as many times as you want, but please see the live checklist before you go live.

Please note that when your merchant bot is working in test mode, it will only be able to send invoices to those Telegram users that are mutual contacts with the account of the bot's creator. So make sure that those who will help you test the payments functionality are in your contacts list.

Step-by-Step Process

1. Create Invoice

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, as well as requested shipping info.

Use the sendInvoice method to do this. 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.

An invoice message with a pay button can only be sent to a private chat with the user. Groups and channels are not supported. The resulting invoice message will look like this:

Invoice in Chat

2. Shipping info and other details (optional step)

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.

Shipping Info

3. Offer delivery options based on shipping address (optional step)

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).

4. Select delivery option (optional step)

The user selects a delivery option from the list (the overall amount to be paid may change at this point) and proceeds to checkout.

Choose Delivery Option

5. Pre-Checkout

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 steel bear instead?"). Telegram will display this reason to the user.

6. Checkout

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.

For the user, the Invoice message in the UI becomes a Receipt — they can open this receipt at any time and see all the details of the transaction:

Receipt

Going Viral: Deep Linking

Note the arrow button on the right of the receipt message on the screenshot above. This quick forwarding button allows the user to select multiple friends, groups, or channels and send the message to them immediately. Thanks to this button, your goods and services can spread virally — the resulting message will have a button that leads users to your bot and asks it to create a similar invoice.

For the quick forwarding button to work correctly, all your invoice messages must contain a start_parameter for creating a new invoice. More info on Deep Linking »

Going Live

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!

Before your merchant bot goes into live mode, please ensure the following:

Live Checklist

  • We highly recommed turning on 2-step verification for the Telegram account that controls your bot.
  • You as the bot owner have full responsibility in case any conflicts or disputes arise. You must be prepared to correctly process disputes and chargebacks (in the case of Stripe, see here and here).
  • To prevent any misunderstandings and possible legal issues, make sure your bot can respond to a /terms command (or offers a similarly easy way of accessing your Terms and Conditions). Your Terms and Conditions should be written in a clear way and easy to understand for your users. The users must confirm that they have read and agree to your terms before they make the purchase.
  • Your bot must provide support for its customers, either by responding to a /support command or by some other clearly communicated means. Users must have a clear way of contacting you about their purchases and you must process their support requests in a timely fashion. You must notify your users that Telegram support or bot support will not able to help them with purchases made via your bot.
  • Make sure that your server hardware and software is stable. Use backups to make sure that you don‘t lose data about your users’ payments.
  • Make sure that you have completed the live checklist for your selected payments provider as well as this one.

Supported Currencies

Telegram payments currently support the currencies listed below (here's a JSON version in case you need it).

If you're using Stripe as the payments provider, supported currencies may vary depending on the country you have specified in your Stripe account (more info).

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 8 digits or less, so the maximum value will be correspondingly lower for some lower-value currencies like the Serbian dinar. 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).

Code Title Min amount Max amount
AED United Arab Emirates Dirham AED 3.67 AED 36,725.02
AFN Afghan Afghani AFN68.16 AFN681,600.04
ALL Albanian Lek 120,05ALL 999.999,99ALL
AMD Armenian Dram 481.26 AMD 999,999.99 AMD
ARS Argentine Peso ARS 15,99 ARS 159.997,43
AUD Australian Dollar AU$1.34 AU$13,439.70
AZN Azerbaijani Manat 1,70 AZN 17 015,03 AZN
BAM Bosnia & Herzegovina Convertible Mark 1,75 BAM 17.513,01 BAM
BDT Bangladeshi Taka BDT 80.72 BDT 807,200.01
BGN Bulgarian Lev 1,74 BGN 17 468,97 BGN
BND Brunei Dollar BND1,38 BND13.833,98
BOB Bolivian Boliviano BOB 6,89 BOB 68.983,39
BRL Brazilian Real R$ 3,25 R$ 32.596,01
CAD Canadian Dollar CA$1.34 CA$13,452.40
CHF Swiss Franc 0.97 CHF 9'734.30 CHF
CLP Chilean Peso CLP 672 CLP 6.721.500
CNY Chinese Renminbi Yuan CN¥6.85 CN¥68,524.02
COP Colombian Peso COP 2.908,10 COP 999.999,99
CRC Costa Rican Colón CRC573,05 CRC999.999,99
CZK Czech Koruna 23,59 CZK 235 979,73 CZK
DKK Danish Krone 6,65 DKK 66516,10 DKK
DOP Dominican Peso DOP47.11 DOP471,199.99
DZD Algerian Dinar DZD 108.35 DZD 999,999.99
EGP Egyptian Pound EGP 18.00 EGP 180,002.15
EUR Euro 0,89 € 8 933,98 €
GBP British Pound £0.77 £7,787.30
GEL Georgian Lari 2,40 GEL 24 071,97 GEL
GTQ Guatemalan Quetzal GTQ7.34 GTQ73,479.71
HKD Hong Kong Dollar HK$7.79 HK$77,929.02
HNL Honduran Lempira HNL 23.39 HNL 233,978.74
HRK Croatian Kuna 6,63 HRK 66.312,00 HRK
HUF Hungarian Forint 274,89 HUF 999 999,99 HUF
IDR Indonesian Rupiah IDR13.320,00 IDR999.999,99
ILS Israeli New Sheqel ₪ 3.56 ₪ 35,686.98
INR Indian Rupee ₹64.54 ₹645,400.01
ISK Icelandic Króna 100 ISK 1.000.000 ISK
JMD Jamaican Dollar JMD129.75 JMD999,999.99
JPY Japanese Yen ¥111 ¥1,113,320
KES Kenyan Shilling KES103.09 KES999,999.99
KGS Kyrgyzstani Som 67-99 KGS 679 940-03 KGS
KRW South Korean Won ₩1,118 ₩11,188,499
KZT Kazakhstani Tenge KZT310-67 KZT999 999-99
LBP Lebanese Pound LBP 1,505.59 LBP 999,999.99
LKR Sri Lankan Rupee LKR 152.60 LKR 999,999.99
MAD Moroccan Dirham MAD 9.75 MAD 97,587.97
MDL Moldovan Leu 18.09 MDL 180,949.99 MDL
MNT Mongolian Tögrög MNT2 401,33 MNT999 999,99
MUR Mauritian Rupee MUR34.34 MUR343,402.22
MVR Maldivian Rufiyaa 15.35 MVR 153,597.06 MVR
MXN Mexican Peso MX$18.45 MX$184,592.02
MYR Malaysian Ringgit MYR4.25 MYR42,594.99
MZN Mozambican Metical MZN58.70 MZN587,000.01
NGN Nigerian Naira NGN321.00 NGN999,999.99
NIO Nicaraguan Córdoba NIO 29.91 NIO 299,141.01
NOK Norwegian Krone NOK 8,39 NOK 83 997,03
NPR Nepalese Rupee NPR102.80 NPR999,999.99
NZD New Zealand Dollar NZ$1.41 NZ$14,136.04
PAB Panamanian Balboa PAB 1.00 PAB 10,000.00
PEN Peruvian Nuevo Sol PEN 3.27 PEN 32,725.01
PHP Philippine Peso PHP49.77 PHP497,799.99
PKR Pakistani Rupee PKR104.83 PKR999,999.99
PLN Polish Złoty 3,73 PLN 37 305,05 PLN
PYG Paraguayan Guaraní PYG 5.605 PYG 56.054.986
QAR Qatari Riyal QAR 3.64 QAR 36,402.97
RON Romanian Leu 4,07 RON 40.763,98 RON
RSD Serbian Dinar 109,61 RSD 999.999,99 RSD
RUB Russian Ruble 56,47 RUB 564 737,01 RUB
SAR Saudi Riyal SAR 3.75 SAR 37,500.96
SEK Swedish Krona 8,69 SEK 86.916,10 SEK
SGD Singapore Dollar SGD1.38 SGD13,839.20
THB Thai Baht ฿34.09 ฿340,901.56
TJS Tajikistani Somoni 8;81 TJS 88 195;02 TJS
TRY Turkish Lira 3,57 TRY 35.766,99 TRY
TTD Trinidad and Tobago Dollar TTD6.70 TTD67,094.98
TWD New Taiwan Dollar NT$30.16 NT$301,698.76
TZS Tanzanian Shilling TZS2,229.99 TZS999,999.99
UAH Ukrainian Hryvnia 26,35UAH 263 501,88UAH
UGX Ugandan Shilling UGX3,596 UGX35,969,998
USD United States Dollar $1.00 $10,000.00
UYU Uruguayan Peso UYU 28,20 UYU 282.099,99
UZS Uzbekistani Som 3 800,00 UZS 999 999,99 UZS
VND Vietnamese Đồng 22.739 ₫ 99.999.999 ₫
YER Yemeni Rial YER 249.92 YER 999,999.99
ZAR South African Rand ZAR 12.94 ZAR 129,404.99