Платежи с использованием 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-бота.

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

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

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

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

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

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

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

При проведении платежей с использованием 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, с информацией о деталях покупки пользователя и о предпочтительном для мерчанта варианте аутентификации.

Так, в соответствии с описанием 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 для получения оповещений.

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