Платежи с использованием Telegram‑бота

Общая информация

Обзор

В платёжной платформе ecommpay поддерживается возможность проведения платежей с использованием Telegram‑ботов — программных компонентов, которые позволяют автоматизировать процессы взаимодействия с пользователями с использованием сервиса Telegram и поддерживают для этого соответствующие интерфейсы:

  • интерфейс для взаимодействия с пользователями в виде специальной учётной записи Telegram;
  • интерфейс для управления со стороны мерчанта в виде специализированного API.

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

Для проведения таких платежей используется платёжная форма Payment Page, которая отображается пользователю непосредственно в мобильном приложении Telegram (в том числе при использовании версий для планшетов). В процессе проведения платежа может потребоваться выполнение вспомогательных процедур, таких как аутентификация 3‑D Secure, дополнение информации о платеже и конвертация валют. Эти процедуры полностью выполняются на стороне Payment Page и не требуют каких-либо дополнительных действий со стороны мерчанта.

Поскольку такие платежи проводятся с использованием платёжной формы Payment Page, со стороны мерчанта предоставление копии сертификата соответствия требованиям PCI DSS не обязательно, однако при отсутствии такого сертификата необходимо заполнить лист самооценки соответствия этим требованиям.

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

Возможности

При проведении платежей с использованием Telegram-бота используется платёжная форма Payment Page, в рамках работы с которой доступны следующие возможности:

  • Использование различных языков (подробнее).
  • Поддержка индивидуального дизайна платёжной формы (подробнее).
  • Сбор дополнительных данных о пользователе (подробнее).
  • Дополнение информации о платеже (подробнее).
  • Аутентификации 3‑D Secure (подробнее).
  • Поддержка повторных попыток оплаты в случае ошибок (подробнее).
  • Предоставление пользователю информации о платеже: отображение на всех страницах платёжной формы кнопки, при использовании которой отображаются данные о сумме, идентификаторе и дате проведения платежа, а также его описание.
  • Отправка уведомлений пользователям (подробнее).

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

Кроме того, при использовании Telegram-бота доступны дополнительные возможности, поддерживаемые со стороны сервиса Telegram, такие как выбор пользователем одного из вариантов доставки с добавлением соответствующей суммы доставки к сумме платежа или отображение причины отказа при оформлении заказа (например, отсутствие нужного товара на складе мерчанта). Информация об использовании таких возможностей представлена в документации Telegram Bot Payments API.

Ограничения

Проведение оплат через сервис Telegram при работе с платформой ecommpay возможно с учётом следующих ограничений:

  • У пользователя установлена версия не ниже указанной в документации сервиса Telegram.
  • Валюта платежа соответствует евро (EUR), долларам США (USD) или фунтам стерлингов (GBP), в противном случае выполняется конвертация на стороне платёжной платформы (подробнее).
  • Сумма платежа поддерживается на стороне сервиса Telegram (подробнее — по ссылке), а также на стороне провайдера или платёжной системы (подробнее — у курирующего менеджера ecommpay).
  • Страна мерчанта соответствует одной из следующих европейских стран: Австрия, Бельгия, Болгария, Великобритания, Германия, Гибралтар, Дания, Испания, Италия, Кипр, Латвия, Лихтенштейн, Люксембург, Мальта, Нидерланды, Норвегия, Польша, Португалия, Румыния, Словакия, Словения, Финляндия, Франция, Хорватия, Чешская Республика, Швейцария, Швеция, Эстония.
  • Сообщение с кнопкой оплаты отправляется в чат между ботом мерчанта и пользователем. Отправка таких сообщений в группы и каналы не поддерживается со стороны сервиса Telegram.

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

Подключение и использование

Для подключения возможности проведения платежей с использованием сервиса Telegram необходимо:

  1. Решить организационные вопросы, касающиеся взаимодействия с ecommpay:
    • Если у компании нет идентификатора проекта для взаимодействия с ecommpay — отправить заявку на подключение (https://ecommpay.com/apply-now/).
    • Если у компании есть идентификатор проекта для взаимодействия с ecommpay — приступить к выполнению подготовительных технических работ (подробнее).
  2. Создать бота (или использовать созданный ранее), разработать для него программный код в соответствии с Telegram Bot API и подготовить его к приёму платежей в соответствии с Telegram Bot Payments API (или MTProto API).
  3. Подключить к боту мерчанта тестовый бот ecommpay (@ECOMMPAY_testbot).
  4. Протестировать и запустить проведение платежей в работу. Для тестирования следует использовать тестовый бот ecommpay и данные тестовых карт, которые представлены в разделе Тестовые карты.
  5. Подключить к боту мерчанта рабочий бот ecommpay (@ECOMMPAY_livebot).

Подробная информация о подготовке бота мерчанта и подключении к нему тестового и рабочего ботов ecommpay представлена далее. При возникновении вопросов по этим процедурам можно обращаться к специалистам технической поддержки ecommpay (support@ecommpay.com).

Пользовательские сценарии

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

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

Оплата без использования сохранённых данных

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

  2. Пользователь подтверждает готовность оплатить заказ и ему отображается платёжная форма Payment Page в режиме Card Tokenize с полями для указания данных платёжной карты, за исключением её кода проверки подлинности (такого как CVV).

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

  4. Пользователь подтверждает готовность оплатить заказ.

  5. Пользователю отображается платёжная форма Payment Page в режиме Purchase, после чего он указывает код проверки подлинности карты и соглашается с проведением оплаты.

  6. Пользователю отображается страница ожидания, а также, если это необходимо для проведения платежа, страницы аутентификации 3‑D Secure и (или) дополнения информации о платеже.

  7. Пользователь перенаправляется к боту мерчанта и ему отображается информация о результате платежа с возможностью просмотра «чека».

Оплата с использованием сохранённых данных

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

  2. Пользователь выбирает платёжные данные, с использованием которых необходимо провести оплату.

  3. Пользователю отображается сообщение от сервиса Telegram и он подтверждает готовность оплатить заказ.

  4. В платёжной форме Payment Page в режиме Purchase пользователь указывает код проверки подлинности карты и соглашается с проведением оплаты.

  5. Пользователю отображается страница ожидания, а также, если это необходимо для проведения платежа, страницы аутентификации 3‑D Secure и (или) дополнения информации о платеже.
  6. Пользователь перенаправляется к боту мерчанта и ему отображается информация о результате платежа с возможностью просмотра «чека».

Подготовка бота

Создание бота

Чтобы создать Telegram-бота, необходимо:

  1. В интерфейсе Telegram найти бота BotFather (@botfather) и открыть чат с ним.
  2. В открывшемся чате выполнить команду /newbot, после чего следовать инструкциям бота.

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

Подключение к тестовому боту ecommpay

Чтобы подключить бот мерчанта к тестовому боту ecommpay (@ECOMMPAY_testbot), необходимо:

  1. В интерфейсе Telegram найти бота BotFather (@botfather) и открыть чат с ним.
  2. В открывшемся чате выполнить команду /mybots и выбрать из списка требуемого бота мерчанта.
  3. В меню настроек выбранного бота щёлкнуть кнопку Payments и выбрать ecommpay из списка, а затем щёлкнуть кнопку Connect ECOMMPAY Test.
  4. В открывшемся чате сначала щёлкнуть кнопку Старт, затем — кнопку Запросить доступ к ECOMMPAY TEST ENVIROMENT.
  5. Если для используемой учётной записи Telegram ранее не подключались боты ecommpay — перейти по ссылке, после чего заполнить и отправить заявку на подключение к боту ecommpay.
  6. Принять от ecommpay информацию о готовности проводить тестовые платежи с использованием Telegram-бота.

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

Подключение к рабочему боту ecommpay

Чтобы подключить к боту мерчанта рабочий бот ecommpay (@ECOMMPAY_livebot), необходимо:

  1. В интерфейсе Telegram найти бота BotFather (@botfather) и открыть чат с ним.
  2. В открывшемся чате выполнить команду /mybots и выбрать из списка требуемого бота мерчанта.
  3. В меню настроек выбранного бота щёлкнуть кнопку Payments и выбрать ecommpay из списка, а затем щёлкнуть кнопку Connect ECOMMPAY Live.
  4. В открывшемся чате сначала щёлкнуть кнопку Старт, затем — кнопку Запросить доступ к ECOMMPAY Live Bot.
  5. Если для используемой учётной записи Telegram ранее не подключались боты ecommpay — перейти по ссылке, после чего заполнить и отправить заявку на подключение к боту ecommpay.
  6. Принять от ecommpay информацию о готовности проводить реальные платежи с использованием Telegram-бота.

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

Аутентификация в сервисе Telegram

В отличие от проведения платежей через API, при проведении платежей с использованием Telegram-бота цифровая подпись не применяется. Вместо этого аутентификация обеспечивается использованием двух токенов: авторизационного, который требуется для получения и отправки сообщений с помощью API Telegram, и платёжного, который требуется для проведения тестовых или реальных платежей. Эти токены формируются при создании бота мерчанта и при подключении к боту ecommpay соответственно.

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

Проведение оплаты

Для проведения оплаты со стороны бота мерчанта необходимо:

  • Отправить к сервису Telegram запрос на оплату и принять ответ о его приёме.
  • Подтвердить проведение оплаты и принять ответ об успешном подтверждении.
  • Принять от сервиса Telegram информацию о результате проведения оплаты.

При этом все взаимодействия с сервисом Telegram необходимо осуществлять в соответствии с описаниями Telegram Bot Payments API (или MTProto API).

В процессе проведения оплаты может возникнуть необходимость выполнения вспомогательных процедур, таких как аутентификация 3‑D Secure, дополнение информации о платеже или конвертация валют. Эти процедуры полностью выполняются на стороне Payment Page и не требуют дополнительных действий со стороны мерчанта.

Проведение оплаты в одну стадию в базовом случае — без выполнения дополнительных процедур — соответствует представленной схеме.



Рис. 1. Проведение оплаты
  1. Пользователь инициирует оплату — в интерфейсе Telegram, в веб-сервисе или иным способом — в результате чего к боту мерчанта поступает соответствующая информация.
  2. От бота мерчанта к сервису Telegram направляется запрос на проведение оплаты.
  3. От сервиса Telegram к боту мерчанта направляется сообщение об успешном приёме этого запроса.
  4. От сервиса Telegram к боту ecommpay направляется запрос на инициирование оплаты.
  5. Запрос на инициирование оплаты поступает в платёжную платформу ecommpay.
  6. В платёжной платформе выполняется обработка запроса.
  7. От платёжной платформы к сервису Telegram направляется сообщение с платёжной ссылкой.
  8. Пользователю отображается сообщение с платёжной ссылкой.
  9. Пользователь переходит по платёжной ссылке.
  10. Запрос на открытие платёжной формы поступает в платёжную платформу.
  11. В платёжной платформе осуществляется обработка запроса.
  12. Осуществляется подготовка Payment Page к сеансу работы в режиме Card Tokenize.
  13. Пользователю отображается подготовленная платёжная форма.
  14. Пользователь указывает реквизиты платёжной карты.
  15. От Payment Page к платёжной платформе направляется запрос на формирование одноразового токена этой карты.
  16. В платёжной платформе выполняется обработка запроса.
  17. От платёжной платформы к сервису Telegram направляется одноразовый токен карты.
  18. Пользователю в сервисе Telegram отображается страница подтверждения оплаты.
  19. Пользователь подтверждает готовность проводить оплату.
  20. От сервиса Telegram к боту мерчанта направляется сообщение с информацией об оплате.
  21. От бота мерчанта к сервису Telegram направляется сообщение с подтверждением оплаты.
  22. От сервиса Telegram к боту мерчанта направляется сообщение об успешном подтверждении оплаты.
  23. От сервиса Telegram к боту ecommpay направляется запрос на подтверждение оплаты.
  24. Запрос на подтверждение оплаты поступает в платёжную платформу ecommpay.
  25. В платёжной платформе выполняется обработка запроса (с проверкой наличия ранее сформированного токена).
  26. От платёжной платформы к сервису Telegram направляется сообщение с платёжной ссылкой.
  27. Со стороны сервиса Telegram выполняется перенаправление пользователя к платёжной форме.
  28. Пользователь перенаправляется к платёжной форме.
  29. Запрос на открытие платёжной формы поступает в платёжную платформу.
  30. В платёжной платформе осуществляется обработка запроса.
  31. Осуществляется подготовка Payment Page к сеансу работы в режиме Purchase.
  32. Пользователю отображается подготовленная платёжная форма.
  33. Пользователь указывает код проверки подлинности карты.
  34. От Payment Page к платёжной платформе направляется запрос на подтверждение оплаты.
  35. В платёжной платформе выполняется обработка запроса и его отправка в платёжную среду.
  36. В платёжной среде выполняется обработка платежа.
  37. От платёжной среды к платёжной платформе направляется уведомление о результате платежа
  38. От платёжной платформы к Payment Page направляется информация о результате платежа.
  39. От платёжной платформы к сервису Telegram направляется информация о результате платежа.
  40. От сервиса Telegram к боту мерчанта направляется информация о результате платежа.
  41. Со стороны сервиса Telegram выполняется перенаправление пользователя к боту мерчанта.
  42. Пользователь перенаправляется к боту мерчанта.
  43. Пользователю отображается информация о результате (с возможностью просмотра «чека»).

Открытие платёжной формы

При проведении платежей с использованием Telegram-бота открытие платёжной формы осуществляется через отправку пользователю сообщения с информацией о платеже и его переход к оплате при помощи соответствующей кнопки в этом сообщении. Для этого на стороне веб-сервиса мерчанта необходимо реализовать отправку HTTPS-запроса sendInvoice методами GET или POST в соответствии с описанием Telegram Bot Payments API либо messages.sendMedia в соответствии с описанием MTProto API.

Дополнительно к параметрам, обязательным для такого запроса, в объекте provider_data можно передавать параметры с информацией о платеже или пользователе, а также параметры, влияющие на отображение платёжной формы пользователю. К таким параметрам относятся:

  • Параметры с дополнительной информацией о пользователе:
    • customer_birthplace — место рождения пользователя;
    • customer_day_of_birth — дата рождения пользователя в формате ДД-ММ-ГГГГ;
    • customer_email — адрес электронной почты пользователя;
    • customer_first_name — имя пользователя;
    • customer_last_name — фамилия пользователя;
    • customer_middle_name — отчество пользователя;
    • customer_phone — номер телефона пользователя (от 4 до 24 цифр);
    • customer_ssn — последние 4 цифры номера социального страхования гражданина США;
    • identify_doc_number — номер документа, подтверждающего личность пользователя.
  • Параметры с информацией об адресе пользователя:
    • customer_address — адрес пользователя;
    • customer_city — город адреса пользователя;
    • customer_country — код страны адреса пользователя в формате ISO 3166-1 alpha-2;
    • customer_state — штат адреса пользователя;
    • customer_street — улица адреса пользователя;
    • customer_zip — почтовый индекс адреса пользователя;
  • Параметры с информацией о платёжном адресе пользователя:
    • billing_address — улица платёжного адреса пользователя;
    • billing_city — город платёжного адреса пользователя;
    • billing_country — код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2;
    • billing_postal — почтовый индекс платёжного адреса пользователя;
    • billing_region — штат, провинция или регион платёжного адреса пользователя;
    • billing_region_code — код штата, провинции или региона страны в формате ISO 3166-2 (используется совместно с параметром billing_country);
  • Параметры с дополнительной информацией о платеже:
    • addendum_data — строка, полученная в результате кодирования с применением алгоритма Base64, с расширенной информацией о бронировании, например номером брони и именами гостей отеля;
    • best_before — дата и время срока действия платежа в формате YYYY-MM-DDThh:mm:ss±hh;
    • receipt_data — строка, полученная в результате кодирования с применением алгоритма Base64, с данными для отправки уведомления пользователю;
    • descriptor — краткая информация, идентифицирующая мерчанта.
  • Параметры, влияющие на отображение платёжной формы:
    • language_code — код языка, на котором платёжная форма открывается пользователю;
    • region_code — код страны пользователя в формате ISO 3166 alpha-2.
  • Параметры, влияющие на вероятность выбора варианта аутентификации frictionless flow (подробнее):
    • customer_account_info — строка, полученная в результате кодирования с применением алгоритма Base64, с информацией об учётной записи пользователя на стороне веб-сервиса и о его контактных данных;
    • customer_shipping — строка, полученная в результате кодирования с применением алгоритма Base64, с информацией о доставке товара или услуги пользователю;
    • payment_merchant_risk — строка, полученная в результате кодирования с применением алгоритма Base64, с информацией о деталях покупки пользователя и о предпочтительном для мерчанта варианте аутентификации.
Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. К параметрам, которые становятся обязательными для таких случаев, относятся customer_email и customer_phone (должен быть передан по крайней мере один из этих параметров).

Так, в соответствии с описанием Telegram Bot API параметры запроса на отправку сообщения для оплаты могут выглядеть следующим образом:

{
    "chat_id": 0007, // Идентификатор целевого чата
    "title": "How to communicate with aliens", // Наименование товара или услуги
    "description": "A book", // Описание товара или услуги
    "payload": "telegram_payment_1204", // Идентификатор платежа
    "provider_token": "12343124:LIVE:42345", // Платёжный токен, сформированный 
                                             // после подключения бота ecommpay
    "start_parameter": "...",
    "currency": "EUR", // Код валюты платежа в формате ISO-4217 alpha-3
    "prices": [{
        "label": "How to communicate with aliens",
        "amount": 5990
    }],
    // Объект с параметрами открытия платёжной формы
    "provider_data": {
        "language_code": "RU", // Код языка в формате ISO 639-1 alpha-2 
                               // для отображения платёжной формы на этом языке
        "customer_email": "janedoe@example.com" // Адрес электронной почты пользователя
    }
}

Подробное описание параметров, доступных для передачи в составе объекта provider_data, представлено в разделе Параметры вызова платёжной формы.

Сбор данных о пользователе

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

Для передачи дополнительных данных о пользователе в объекте provider_data необходимо задать список дополнительных параметров и их значения. В этом случае переданные данные отображаются в соответствующих полях платёжной формы, если такая возможность настроена специалистами технической поддержки.

Для запроса дополнительных данных о пользователе в объекте provider_data необходимо задать список дополнительных параметров без их значений. В этом случае в платёжной форме отображаются соответствующие поля для указания данных, если такая возможность настроена специалистами технической поддержки.

Подробная информация о таких данных представлена в разделе Сбор данных о пользователях.

Обработка оповещений

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

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

Индивидуальное оформление

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