Как принимать криптоплатежи в Telegram-боте

Чтобы понять, как принимать криптоплатежи в Telegram-боте, сначала нужно определить, за что платит клиент и какой платежный сценарий допускают правила Telegram. Компании могут использовать прямые переводы между кошельками, Telegram Stars или внешний криптоплатежный шлюз, подключенный через платежные ссылки или API. При автоматизированном сценарии шлюз может создавать инвойсы, отслеживать подтверждения в блокчейне через вебхуки и запускать выдачу товара или доступа там, где это разрешено правилами Telegram.

TL;DR

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

• Telegram Stars — это виртуальная валюта, а не криптовалюта. Для цифровых товаров и услуг внутри Telegram-ботов и Mini Apps оплата через Stars обязательна.

• Переводы с кошелька на кошелек просты в настройке, но обычно требуют ручной сверки платежей.

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

3 способа, которыми компании принимают криптоплатежи через Telegram

Под «криптоплатежами через Telegram» могут подразумеваться три разных сценария. Они отличаются по уровню автоматизации, требованиям комплаенса и ограничениям самой платформы.

Сейчас Telegram требует использовать Telegram Stars для цифровых товаров и услуг, которые продаются внутри ботов и Mini Apps. Поэтому сторонний криптоплатежный API нельзя подавать как способ обойти Stars для цифровых продуктов внутри Telegram. Для физических товаров и допустимых услуг могут использоваться другие способы оплаты.

Методология

Этот гайд подготовлен на основе официальной документации Telegram Bot Payments и Telegram Stars, а также актуальной документации Payment API PassimPay. В примерах используется реальный платежный сценарий: создание платежного запроса, получение статуса, проверка колбэка и запуск исполнения заказа.

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

Зачем принимать криптоплатежи через Telegram?

Telegram-бот может объединить взаимодействие с клиентом и запуск оплаты в одном сценарии. Он может показать инвойс или платежную ссылку, дождаться подтверждения и продолжить работу с пользователем после поступления платежа.

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

Автоматизация — одна из основных причин использовать Telegram bot payment API вместо простой публикации адреса кошелька. Бот может связать идентификатор заказа с платежным запросом, получить вебхук при изменении статуса, обновить заказ и автоматически запустить следующее действие.

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

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

Криптоплатежный шлюз PassimPay предоставляет платежную инфраструктуру, которую можно подключить к Telegram-боту. PassimPay поддерживает 74 криптовалюты и 18+ блокчейнов, комиссии от 0,5%, Платежные ссылки и QR-коды, Payment API, а также Вебхуки и уведомления.

Как принимать криптоплатежи в Telegram-боте: пошаговая инструкция

Выбор Telegram payment bot integration зависит от того, нужен ли вам простой платежный сценарий или полностью автоматизированный чекаут. Платежные ссылки требуют меньше разработки, а API-интеграция дает боту прямой контроль над созданием платежа, отслеживанием статуса и исполнением заказа.

Вариант 1: начать с платежной ссылки или QR-кода

• Создайте аккаунт мерчанта и пройдите верификацию.

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

• Создайте платежный запрос.

Используйте Платежные ссылки и QR-коды, чтобы сформировать ссылку или QR-код на нужную сумму. В PassimPay мерчант может создать платежный запрос без разработки собственного интерфейса оплаты.

• Отправьте платежную ссылку в Telegram.

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

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

• Подтвердите платеж до исполнения заказа.

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

Такой вариант относительно быстро запускается и не требует полноценной интеграции Telegram bot payment API. Однако по мере роста объема платежей ручная проверка становится неудобной.

Вариант 2: подключить полноценную интеграцию Telegram Bot Payment API

API-интеграция подходит, когда бот должен автоматически создавать платежные запросы и обрабатывать статусы оплаты.

• Настройте доступ к API и подключите бота к созданию платежей.

После создания аккаунта мерчанта добавьте платформу и получите данные, необходимые для API-запросов, например API Key и Platform ID. PassimPay требует подписывать API-запросы и передавать подпись в заголовках запроса.

Храните учетные данные API на сервере. Их нельзя передавать в сообщениях Telegram, клиентском коде Mini App или других компонентах на стороне пользователя.

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

• Свяжите каждый платеж с заказом.

Создавайте уникальный идентификатор для каждого платежного запроса. Он должен позволять системе связать пользователя Telegram, товар или услугу, ожидаемую сумму, выбранную криптовалюту и статус платежа.

Использовать только сумму в качестве основного идентификатора заказа не стоит: несколько клиентов могут платить примерно одновременно.

• Настройте и проверяйте вебхуки.

Укажите Notification URL — адрес эндпоинта, который контролирует мерчант. Когда статус платежа меняется, провайдер отправляет на этот адрес вебхук, а бэкенд обновляет соответствующий заказ.

В PassimPay Notification URL задается в настройках платформы. Перед обработкой вебхука необходимо проверить заголовок x-signature, а также IP-адрес отправителя по списку разрешенных IP-адресов PassimPay. Запросы с неизвестных или неавторизованных IP-адресов не следует обрабатывать.

• Обрабатывайте повторные уведомления и возвращайте HTTP 200.

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

Это особенно важно для BTC, LTC, DASH, Dogecoin и Bitcoin Cash. PassimPay может отправить до двух вебхуков по одной транзакции: после первого и второго подтверждения. Если транзакция впервые обнаружена уже с двумя подтверждениями, приходит только один вебхук.

После успешной обработки валидного колбэка по депозиту сервер должен вернуть HTTP 200. Если PassimPay не получает HTTP 200, документация предусматривает еще две попытки повторной отправки уведомления.

• Запустите исполнение заказа и протестируйте весь сценарий.

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

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

Payment API, Платежные ссылки и QR-коды PassimPay поддерживают оба сценария интеграции: ссылки подходят для более простой настройки, а API — для автоматизированной обработки платежей.

Telegram Stars и криптоплатежи: в чем разница?

Telegram Stars и криптоплатежи решают разные задачи.

Telegram Stars — это виртуальная валюта внутри Telegram. Пользователи приобретают Stars через поддерживаемые Telegram платежные сценарии и могут использовать их для оплаты цифровых товаров и услуг, которые предлагаются через ботов и Mini Apps.

Stars не являются криптовалютой. Платежный сценарий контролируется Telegram, и для цифровых товаров и услуг внутри приложений Telegram требуется использовать Stars.

Криптоплатежи используют блокчейн-активы, например BTC, USDT, ETH и другие поддерживаемые криптовалюты. Для них обычно нужен внешний кошелек или платежный провайдер.

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

То же правило действует для платежей в Telegram Mini Apps. Создание Mini App не отменяет требование использовать Stars для цифровых продуктов, которые подпадают под соответствующие правила Telegram.

Для физических товаров и допустимых услуг внешние платежные провайдеры могут использоваться там, где это разрешено правилами Telegram и применимым законодательством.

Комплаенс, безопасность и масштабирование

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

Учитывайте юрисдикцию компании

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

Сам прием криптовалюты в качестве оплаты и оказание регулируемых криптосервисов не всегда подпадают под одинаковые требования. Компаниям стоит отдельно определить, какие правила применяются к их модели.

Учтите требования KYC и AML

Платежный провайдер может потребовать верификацию мерчанта до начала обработки платежей.

Провайдеры также могут использовать AML-мониторинг для проверки входящих транзакций. PassimPay указывает, что зарегистрирован в FINTRAC под номером C100000852, а каждая транзакция проходит AML-проверку до зачисления средств.

Необходимость дополнительной проверки клиентов зависит от провайдера, юрисдикции, типа транзакции и применимых требований комплаенса.

Ведите учет платежей

Криптоплатежи также нужно учитывать для бухгалтерской и финансовой отчетности.

Компании стоит сохранять следующие данные:

• идентификатор заказа;

• криптовалюта и блокчейн;

• сумма в криптовалюте;

• применимая стоимость в фиате;

• хеш транзакции;

• время платежа;

• комиссии провайдера;

• данные о расчетах;

• информация о возврате средств, если он проводился.

Требования к бухгалтерскому и налоговому учету зависят от юрисдикции.

Управляйте волатильностью криптовалют

Если бот принимает оплату в волатильных активах, например BTC, стоимость полученных средств может измениться уже после транзакции.

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

PassimPay предлагает Автоконвертацию в стейблкоины, которая может переводить входящие платежи в USDT или USDC. Компании, которые предпочитают принимать оплату сразу в стейблкоине, также могут использовать платежный шлюз USDT.

Защитите данные доступа к API и webhook-эндпоинты

API-ключи должны храниться на сервере. Их нельзя отправлять клиентам или размещать в публично доступном коде бота.

Подпись вебхука нужно проверять до изменения статуса заказа. Административные команды бота также следует защищать от неавторизованного доступа.

Платежные события стоит журналировать, чтобы позже можно было разобраться с неуспешными или спорными транзакциями.

Подготовьтесь к масштабированию

Схема, которая работает для десяти платежей, может оказаться недостаточной для тысяч транзакций.

Отслеживайте неуспешные колбэки, задержки подтверждений в блокчейне, недоступность отдельных сетей, простои провайдера и необычную платежную активность.

У компании также должен быть резервный сценарий на случай, если автоматическое исполнение заказа не сработало, хотя сам платеж уже подтвержден.

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

FAQ

Можно ли принимать криптоплатежи прямо в Telegram без отдельного сайта?

Отдельный сайт нужен не всегда. Бот может отправлять внешнюю платежную ссылку для оплаты в криптовалюте или подключаться к API. Однако цифровые товары и услуги внутри Telegram-ботов и Mini Apps сейчас должны оплачиваться через Telegram Stars в соответствии с правилами платформы.

Чем Telegram Stars отличаются от криптоплатежей?

Telegram Stars — виртуальная валюта внутри Telegram, а не криптовалюта. Криптоплатежи используют блокчейн-активы, например BTC или USDT. Для цифровых товаров и услуг внутри Telegram требуется использовать Stars, тогда как другие способы оплаты могут применяться для допустимых физических товаров и услуг.

Законно ли принимать криптоплатежи через Telegram-бота?

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

Как интегрировать API для криптоплатежей в Telegram-бота?

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

Как быстро подтверждаются криптоплатежи в Telegram-боте?

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

Нужно ли проходить KYC, чтобы принимать криптоплатежи в Telegram?

Платежный провайдер обычно требует верификацию мерчанта до подключения платежных услуг. Нужен ли KYC для клиентов, зависит от провайдера, юрисдикции, типа транзакции и риск-контроля. Верификация аккаунта Telegram не заменяет комплаенс-проверки платежного провайдера.

Читайте также

• Как принимать криптоплатежи на сайте WordPress

• Продукты PassimPay

Итоги

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

При небольшом объеме платежей Платежные ссылки и QR-коды могут быть более простым вариантом для старта. Для автоматизированной обработки мерчанты могут подключить Telegram bot payment API к бэкенду и использовать проверенный статус платежа как триггер для следующего действия.

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