💰 Telegram Bot Payments API

Платежи за физические товары

Платежи за физические товары и услуги были впервые добавлены в Telegram в 2017 году и позволяют ботам:

• Принимать платежи из более чем 200 стран с использованием более 20 провайдеров.
• Отправлять счета в любой чат, включая группы и каналы.
• Получать платежи от пользователей на мобильных или десктопных приложениях.
• Попробовать @ShopBot для создания тестового счета – или начать сообщение с @ShopBot ... в любом чате для инлайн-счета.
• Посмотреть Демо Магазин для примера Telegram Канала, используемого как виртуальный магазин.

Посмотрите @ShopBot для примера виртуального магазина – затем используйте наши специализированные руководства для цифровых и физических продуктов, чтобы создать свой собственный.

Как это работает?

Вы создаете бота, который предлагает товары и услуги пользователям Telegram. Торговые боты могут отправлять специально отформатированные сообщения-счета пользователям, группам или каналам. Если ваш бот поддерживает инлайн-режим, пользователи также могут отправлять счета в другие чаты через бота, включая личные чаты с другими пользователями.

Сообщения-счета содержат фото и описание продукта, а также заметную кнопку Оплатить. Нажатие на эту кнопку открывает специальный интерфейс оплаты в приложении Telegram. В этом интерфейсе пользователи могут выбрать сумму чаевых (если это разрешено торговцем) и ввести дополнительные данные, такие как информация о доставке, номер телефона или адрес электронной почты.

Бот может предложить несколько вариантов доставки для физических товаров в зависимости от адреса доставки. Когда все готово, пользователи вводят данные своей кредитной карты или выбирают сохраненную карту — и оплачивают товар. Telegram также поддерживает Apple Pay и Google Pay. После завершения транзакции торговый бот может отправить сообщение-чеки с деталями оплаты, информацией о доставке и доставке.

Подробная информация и пошаговые инструкции доступны ниже.

Платежи через сторонних поставщиков

Telegram не обрабатывает платежи от пользователей и вместо этого позволяет разработчикам интегрироваться напрямую с различными сторонними поставщиками платежей по всему миру. Именно поставщики платежей обрабатывают и хранят всю конфиденциальную информацию, такую как данные кредитных карт. Ни Telegram, ни разработчики ботов не имеют к ней доступа.

Если вы работаете в компании, предоставляющей услуги, аналогичные самостоятельным аккаунтам в Stripe Connect, пожалуйста, дайте нам знать через @BotSupport (включите хештег #paymentsprovider в ваше сообщение).

---

Платежный API

В этом разделе рассматриваются платежи через Bot API Telegram более подробно.

Подключение платежей

Чтобы начать принимать платежи, вам нужен Telegram-бот. Используйте BotFather, чтобы создать бота, если у вас его еще нет.

Теперь у вас есть торговый бот, который может предлагать товары или услуги пользователям Telegram. В этом документе мы будем называть его @merchantbot.

Получение токена

• Используйте команду /mybots в чате с BotFather и выберите @merchantbot, который будет предлагать товары или услуги.
• Перейдите в Настройки бота > Платежи.
• Выберите провайдера, и вы будете перенаправлены к соответствующему боту.
• Введите необходимые данные, чтобы успешно подключить провайдера платежей, затем вернитесь в чат с Botfather.
• Теперь сообщение будет показывать доступные провайдеры. Каждый из них будет иметь имя, токен и дату подключения провайдера.
• Вы будете использовать токен при работе с Bot API.

Реализация платежей

Необходимые методы для создания вашей реализации платежей вы найдете в Разделе Платежей Руководства по Bot API.

Тестирование платежей: провайдер 'Stripe TEST MODE'

Пока вы все еще разрабатываете и тестируете платежи для вашего бота, используйте провайдер “Stripe TEST MODE”. В этом режиме вы можете совершать платежи, не списывая средства с реальных счетов. Реальные карты не могут быть использованы в тестовом режиме, но вы можете использовать тестовые карты, такие как 4242 4242 4242 4242 (полный список здесь). Вы можете переключаться между тестовым режимом и живым режимом столько раз, сколько захотите, но, пожалуйста, ознакомьтесь с чек-листом для выхода в живую перед тем, как выйти в живую.

Пошаговый процесс

Смотрите Bot API: Платежи для полного списка доступных методов и объектов.

1. Создание счета

Пользователь связывается с @merchantbot и запрашивает покупку чего-либо. Бот формирует сообщение-счет с описанием товара или услуги, суммой к оплате и запрашиваемой информацией о доставке. Существует два способа создания счета:

A. Счет от бота

Используйте метод sendInvoice для генерации счета и отправки его в чат. Параметр provider_token — это то место, куда вы помещаете значение token, который вы получили ранее через Botfather. Один торговый бот может использовать несколько различных токенов для разных пользователей или разных товаров и услуг.

Сообщения-счета с кнопкой оплаты могут быть отправлены в чаты любого типа: личные чаты с пользователем, группы или каналы. Полученное сообщение-счет будет выглядеть так:

B. Инлайн-счет

Если @merchantbot поддерживает инлайн-режим, вы можете использовать inputInvoiceMessageContent, чтобы позволить пользователям делиться счетами за ваши товары и услуги в их личных чатах с друзьями или в группах и каналах. Эти счета будут иметь Кнопку оплаты, которую можно использовать несколько раз.

2. Выбор поведения пересылки

Существует два способа обработки пересланных копий ваших счетов, контролируемых параметром start_parameter в методе sendInvoice.

• A. Мульти-чат счет. Пересланные копии показывают кнопку Оплатить, которую могут нажимать несколько пользователей и пытаться оплатить товары или услуги. Инлайн-счета всегда являются мульти-чат счетами.
• B. Одно-чат счет. Счет может быть оплачен только из чата, в который он был отправлен, пересланные копии показывают кнопку URL с глубоким ссылкой на бота. Глубокая ссылка может быть использована для генерации аналогичного счета в чате с ботом, для отображения сообщения об ошибке или для других целей. Дополнительная информация о глубоком связывании »

Если одно-чат счет отправляется в чат с @merchantbot, его можно оплатить один раз. Если одно-чат счет отправляется в любой другой чат, его можно оплатить много раз многими пользователями.

Чтобы лучше понять, как это работает, попробуйте переключить параметр “Оплатить из пересылок” при создании счетов с помощью нашего демо @ShopBot.

Независимо от того, доступна ли кнопка Оплатить в счете, бот-продавец всегда имеет возможность решать, принимать ли новые платежи за конкретный счет.

3. Советы (необязательный шаг)

Если параметр max_tip_amount установлен выше 0, пользователи могут добавить чаевые к своему платежу. Вы можете использовать параметр suggested_tip_amounts, чтобы предложить конкретные суммы, которые, по вашему мнению, будут актуальны для счета.

4. Информация о доставке и другие детали (необязательный шаг)

Пользователь указывает информацию о доставке или другую информацию, запрашиваемую ботом. Это может быть полное имя пользователя, адрес электронной почты, номер телефона в международном формате или полный почтовый адрес для доставки.

5. Предложите варианты доставки на основе адреса доставки (необязательный шаг)

Если был запрошен адрес доставки и вы включили параметр is_flexible, Bot API отправит Update с полем shipping_query боту. Бот должен ответить, используя answerShippingQuery, либо с списком возможных вариантов доставки и соответствующими ценами на доставку, либо с ошибкой (например, если доставка по указанному адресу невозможна).

Совет: Рекомендуется, чтобы бот-торговец подтвердил наличие товаров/услуг на этом этапе – чтобы уведомить пользователя в случае, если они больше недоступны. Это особенно важно, если вы используете мульти-чат, инлайн или одиночные чаты, многоразовые счета.

6. Выберите вариант доставки (необязательный шаг)

Пользователь выбирает вариант доставки из списка (общая сумма к оплате может измениться на этом этапе) и переходит к оформлению заказа.

7. Предварительная проверка заказа

Пользователь вводит свои платежные данные и нажимает кнопку окончательной оплаты. В этот момент Bot API отправляет Update с полем pre_checkout_query боту, который содержит всю доступную информацию о заказе. Ваш бот должен ответить, используя answerPrecheckoutQuery, в течение 10 секунд после получения этого обновления, иначе транзакция будет отменена.

Бот может вернуть ошибку, если он не может обработать заказ по какой-либо причине. Мы настоятельно рекомендуем указывать причину неудачи в завершении заказа в понятной для человека форме (например, "Извините, у нас закончились резиновые утки! Вас заинтересует чугунный медведь вместо этого?"). Telegram отобразит эту причину пользователю.

Внимание: Крайне важно убедиться, что ваш бот только принимает множественные платежи, когда заказ может быть обработан правильно. Это особенно важно, если вы используете мульти-чат, инлайн или одиночный чат, многоразовые счета.

8. Оформление заказа

В случае, если бот подтверждает заказ, Telegram запрашивает у платежного провайдера завершение транзакции. Если информация о платеже была введена корректно и платеж проходит, API отправит сообщение-чеки типа successful_payment от пользователя. Как только ваш бот получает это сообщение, он должен продолжить доставку товаров или услуг, приобретенных пользователем.

Если сообщение-счет было отправлено в чате с @merchantbot, оно становится Чеком в пользовательском интерфейсе — пользователь может открыть этот чек в любое время и увидеть все детали транзакции:

Если сообщение было отправлено в любой другой чат, Кнопка оплаты остается и может быть использована снова. Решение о том, принимать ли несколько платежей, остается за торговым ботом.

Запуск в работу

После того как вы протестировали всё и подтвердили, что ваша реализация платежей работает, вы готовы переключиться в РЕАЛЬНЫЙ РЕЖИМ. Для этого перейдите в BotFather > /mybots > выберите @merchantbot > Настройки бота / Платежи и включите Stripe LIVE MODE. Вы получите токен, который содержит строку :LIVE: в середине, например, 123:LIVE:XXXX. Не передавайте этот токен третьим лицам!

Перед тем как ваш торговый бот перейдет в реальный режим, пожалуйста, убедитесь в следующем:

Живой контрольный список

• Мы настоятельно рекомендуем включить двухфакторную аутентификацию для учетной записи Telegram, которая управляет вашим ботом.
• Вы, как владелец бота, несете полную ответственность в случае возникновения конфликтов или споров. Вы должны быть готовы правильно обрабатывать споры и возвраты (в случае с Stripe, смотрите здесь).
• Чтобы избежать недоразумений и возможных юридических проблем, убедитесь, что ваш бот может ответить на команду /terms (или предлагает аналогично простой способ доступа к вашим Условиям и Положениям). Ваши Условия и Положения должны быть написаны понятным языком и легко воспринимаемы вашими пользователями. Пользователи должны подтвердить, что они прочитали и согласны с вашими условиями, прежде чем совершить покупку.
• Ваш бот должен предоставлять поддержку своим клиентам, либо отвечая на команду /support, либо иным четко обозначенным способом. У пользователей должен быть ясный способ связаться с вами по вопросам их покупок, и вы должны обрабатывать их запросы на поддержку своевременно. Вы должны уведомить своих пользователей о том, что поддержка Telegram или поддержка ботов не сможет помочь им с покупками, сделанными через ваш бот.
• Убедитесь, что ваше серверное оборудование и программное обеспечение стабильны. Используйте резервные копии, чтобы не потерять данные о платежах ваших пользователей.
• Убедитесь, что вы завершили живой контрольный список для вашего выбранного поставщика платежей, а также этот.

---

FAQ

Как мне стать платежным провайдером?

Если вы работаете в компании, которая предоставляет услуги, аналогичные отдельным счетам в Stripe Connect, пожалуйста, дайте нам знать через @BotSupport (пожалуйста, включите хэштег #paymentsprovider в ваше сообщение).

Сколько вы берете?

Telegram не взимает комиссию за использование Payments API. Однако имейте в виду, что у большинства платежных провайдеров будут свои комиссии. Например, Stripe в США взимает 2,9% + 30¢ за каждую успешную транзакцию по карте (см. веб-сайт Stripe для получения дополнительной информации о ценах).

Нужен ли мне бот для приема платежей?

Да. Если вы не разработчик, вам нужно будет либо нанять кого-то, чтобы он сделал бота для вас (рекомендуется), либо использовать бота, созданного сторонней компанией. Мы настоятельно рекомендуем проявлять крайнюю осторожность при использовании услуг ботов, которые обрабатывают платежи за вас – Telegram не поддерживает такие боты и не одобряет ни один из сторонних ботов, предлагающих эти услуги.

Что может продавать мой бот?

Telegram не накладывает никаких ограничений на то, какие продукты или услуги может предлагать ваш бот. Но обратите внимание, что вы должны соблюдать правила платежного провайдера, который вы выберете в нашей системе. Например, у Stripe есть специальная страница для запрещенных видов деятельности – вам стоит ознакомиться с ней, прежде чем начать продавать собранные органы.

Особое примечание: Из-за ограничений Apple разработчики ботов в настоящее время не могут принимать платежи за цифровые товары и виртуальные услуги от пользователей iOS.

UPD 2024: Благодаря недавним изменениям в Руководстве по обзору Apple, пользователи скоро смогут оплачивать цифровые товары и услуги с помощью Telegram Stars на всех платформах.

Как обрабатываются споры?

Telegram выступает в роли посредника между платящим пользователем, разработчиком бота и выбранной ими платежной системой. Пользователь отправляет свои данные кредитной карты непосредственно в платежную систему. Затем ответ платежной системы и данные о доставке, введенные пользователем, передаются разработчику бота для обработки заказа.

Поскольку Telegram не обрабатывает платежи, мы не храним и не можем получить доступ к каким-либо конфиденциальным данным. Из-за этой структуры Telegram не может обрабатывать жалобы или возвраты средств – любые спорные платежи являются ответственностью разработчиков ботов, платежных провайдеров и банков, участвующих в обмене.

Смотрите также: Политика конфиденциальности Telegram

Как я могу поддерживать платежи в своем стороннем приложении, которое использует Telegram API?

Вы можете ознакомиться с документацией по платежам MTProto.

Поддерживаемые валюты

Платежи в Telegram в настоящее время поддерживают следующие валюты (вот JSON версия, если вам это нужно).

Если вы используете Stripe в качестве поставщика платежей, поддерживаемые валюты могут различаться в зависимости от страны, указанной в вашей учетной записи Stripe (подробности).

Минимальные и максимальные суммы для каждой из валют примерно соответствуют лимиту US$ 1-10000. Сумма должна быть выражена в 12 цифрах или меньше, поэтому максимальное значение будет соответственно ниже для некоторых валют с низкой стоимостью. Обратите внимание, что для каждой валюты, кроме USD, эти лимиты зависят от обменных курсов и могут изменяться со временем (планируйте это, когда вы реализуете лимиты в своем коде).

Код	Название	Минимальная сумма	Максимальная сумма
AED	Дирхам Объединенных Арабских Эмиратов	AED 3.67	AED 36,724.95
AFN	Афгани	AFN73.00	AFN730,009.17
ALL	Албанский лек	92,06ALL	920.592,10ALL
AMD	Армянский драм	391.99 AMD	3,919,886.12 AMD
ARS	Аргентинское песо	ARS 1.063,74	ARS 10.637.431,99
AUD	Австралийский доллар	AU$1.58	AU$15,790.05
AZN	Азербайджанский манат	1,70 AZN	17 021,77 AZN
BAM	Конвертируемая марка Боснии и Герцеговины	1,81 BAM	18.083,81 BAM
BDT	Бангладешская така	BDT 119.97	BDT 1,199,700.42
BGN	Болгарский лев	1,81 BGN	18 111,00 BGN
BHD	Бахрейнский динар	BHD 0.377	BHD 3,768.750
BND	Доллар Брунея	BND1,32	BND13.203,70
BOB	Боливийский боливиано	BOB 6,82	BOB 68.228,05
BRL	Бразильский реал	R$ 5,75	R$ 57.545,05
BYN	Белорусский рубль	3,23 BYN	32 313,01 BYN
CAD	Канадский доллар	CA$1.44	CA$14,367.20
CHF	Швейцарский франк	0.89 CHF	8'856.60 CHF
CLP	Чилийское песо	CLP 940	CLP 9.397.299
CNY	Китайский юань	CN¥7.25	CN¥72,510.96
COP	Колумбийское песо	COP 4.113,00	COP 41.130.000,00
CRC	Коста-риканский колон	CRC495,97	CRC4.959.663,44
CZK	Чешская крона	23,20 CZK	231 969,83 CZK
DKK	Датская крона	6,91 DKK	69092,20 DKK
DOP	Доминиканское песо	DOP61.55	DOP615,519.75
DZD	Алжирский динар	DZD 133.62	DZD 1,336,222.34
EGP	Египетский фунт	EGP 50.67	EGP 506,712.98
ETB	Эфиопский бирр	ETB128.55	ETB1,285,530.95
EUR	Евро	0,93 €	9 262,70 €
GBP	Британский фунт	£0.78	£7,764.75
GEL	Грузинский лари	2,78 GEL	27 801,79 GEL
GHS	Ghanaian cedi	GHS15.52	GHS155,188.48
GTQ	Guatemalan Quetzal	GTQ7.72	GTQ77,220.50
HKD	Hong Kong Dollar	HK$7.77	HK$77,707.50
HNL	Honduran Lempira	HNL 25.60	HNL 256,023.62
HRK	Croatian Kuna	6,95 HRK	69.544,04 HRK
HUF	Hungarian Forint	367,38 HUF	3 673 803,88 HUF
IDR	Indonesian Rupiah	IDR16.300,00	IDR163.000.000,00
ILS	Israeli New Sheqel	₪ 3.63	₪ 36,288.50
INR	Indian Rupee	₹87.15	₹871,492.50
IQD	Iraqi dinar	IQD 1,311.586	IQD 13,115,858.440
IRR	Iranian rial	42,100 IRR	421,000,003/52 IRR
ISK	Icelandic Króna	136 ISK	1.357.704 ISK
JMD	Jamaican Dollar	JMD156.95	JMD1,569,510.45
JOD	Jordanian dinar	JOD0.709	JOD7,094.040
JPY	Japanese Yen	¥148	¥1,480,450
KES	Kenyan Shilling	KES129.56	KES1,295,621.28
KGS	Kyrgyzstani Som	87-45 KGS	874 503-84 KGS
KRW	South Korean Won	₩1,448	₩14,475,150
KZT	Kazakhstani Tenge	KZT491-34	KZT4 913 394-55
LBP	Lebanese Pound	LBP 89,707.47	LBP 897,074,701.24
LKR	Sri Lankan Rupee	LKR 295.81	LKR 2,958,058.41
MAD	Moroccan Dirham	MAD 9.74	MAD 97,353.39
MDL	Moldovan Leu	18.17 MDL	181,719.19 MDL
MMK	Myanmar kyat	MMK2,099.09	MMK20,990,916.91
MNT	Mongolian Tögrög	MNT3 470,41	MNT34 704 126,98
MOP	Macanese pataca	MOP8.01	MOP80,137.50
MUR	Mauritian Rupee	MUR45.22	MUR452,203.78
MVR	Maldivian Rufiyaa	15.41 MVR	154,103.78 MVR
MXN	Mexican Peso	MX$20.27	MX$202,671.70
MYR	Malaysian Ringgit	MYR4.41	MYR44,145.04
MZN	Mozambican Metical	MZN63.90	MZN639,037.29
NGN	Nigerian Naira	NGN1,515.00	NGN15,150,003.44
NIO	Nicaraguan Córdoba	NIO 36.85	NIO 368,476.91
NOK	Norwegian Krone	NOK 10,86	NOK 108 599,04
NPR	Nepalese Rupee	NPR139.22	NPR1,392,156.14
NZD	New Zealand Dollar	NZ$1.75	NZ$17,511.60
PAB	Panamanian Balboa	PAB 1.00	PAB 10,011.54
PEN	Peruvian Nuevo Sol	PEN 3.66	PEN 36,579.15
PHP	Philippine Peso	PHP57.21	PHP572,050.38
PKR	Pakistani Rupee	PKR280.34	PKR2,803,359.02
PLN	Polish Złoty	3,85 PLN	38 495,82 PLN
PYG	Paraguayan Guaraní	PYG 7.928	PYG 79.278.365
QAR	Qatari Riyal	QAR 3.65	QAR 36,500.72
RON	Romanian Leu	4,59 RON	45.926,04 RON
RSD	Serbian Dinar	108,13 RSD	1.081.345,45 RSD
RUB	Russian Ruble	93,50 RUB	935 034,38 RUB
SAR	Saudi Riyal	SAR 3.75	SAR 37,516.73
SEK	Swedish Krona	10,09 SEK	100.864,04 SEK
SGD	Singapore Dollar	SGD1.33	SGD13,309.04
SYP	Syrian pound	SYP 13,002.47	SYP 130,024,689.47
THB	Thai Baht	฿33.76	฿337,560.38
TJS	Tajikistani Somoni	10;91 TJS	109 131;18 TJS
TRY	Turkish Lira	36,40 TRY	364.008,04 TRY
TTD	Trinidad and Tobago Dollar	TTD6.80	TTD67,964.75
TWD	New Taiwan Dollar	NT$32.84	NT$328,420.38
TZS	Tanzanian Shilling	TZS2,648.18	TZS26,481,797.63
UAH	Ukrainian Hryvnia	41,27UAH	412 664,61UAH
UGX	Ugandan Shilling	UGX3,674	UGX36,736,954
USD	United States Dollar	$1.00	$10,000.00
UYU	Uruguayan Peso	UYU 42,66	UYU 426.613,76
UZS	Uzbekistani Som	12 934,07 UZS	129 340 654,27 UZS
VND	Vietnamese Đồng	25.505 ₫	255.050.000 ₫
YER	Yemeni Rial	YER 246.80	YER 2,468,035.91
ZAR	South African Rand	ZAR 18.25	ZAR 182,514.20