Сегодня хочу рассказать о том, как работать с платежным API не так давно появившегося на просторах Telegram кошелька TeleWallet Статья будет интересна в первую очередь владельцам и разработчикам ботов Telegram, поскольку эта платежная система позволяет принимать платежи в Телеграме, не покидая Telegram
Хочу сразу отметить, что я не выступаю за или против какой-либо платежной системы, а хочу лишь описать, как работать с API.
Преимущества и недостатки
Основные преимущества (на мой взгляд) приема платежей через TeleWallet:
- Низкая комиссия (0.8% суммарно за автопополнение и автовыплату)
- Отсутствие минимальной суммы (точнее, минимальная сумма составляет 0.01)
- Доступность нескольких валют (фиатных и крипто)
- Возможность подключения неограниченного количества проектов на один профиль
Основные недостатки:
- Слабая распространенность ресурса (хотя это скорее всего исправимо)
- Отсутствие английского интерфейса (кошелек рассчитан на русскоязычную аудиторию и соответственно распространенные в СНГ платежные системы)
- Недостаточно автоматизированные переводы средств в сам кошелек (на данный момент доступно автоматическое пополнение кошелька только через Яндек.Деньги и Visa/MasterCard. Для других платежных систем доступно полуавтоматическое пополнение, из-за чего присутствует время ожидания)
Подключение автоплатежей
Итак приступим. Для начала набросаем небольшого тестового бота на PHP c 3-мя кнопками:
- Баланс чтоб просматривать баланс и видеть, что он изменился
- Пополнить
- Вывести
Про регистрацию бота в BotFather рассказывать не буду: слишком уж много сказано до меня на эту тему. Для работы с Telegram-bot-api будем использовать irazasyed/telegram-bot-sdk. Как работать с этим SDK, и кстати как зарегистрировать бота в BotFather и установить webhook на него неплохо описано здесь.
И конечно для работы с TeleWallet API будем использовать их официальный SDK. Там же у них есть подробная инструкция, как работать с платежами и есть примеры кода. Так что ниже я просто покажу как совместить приведенные там примеры кода с реальным ботом.
Создаем платежный счёт
- Перейдите в бота t.me/TeleWalletAbot
- Запустите его
- Нажмите кнопку Прием платежей в главном меню
- Под появившимся сообщением нажмите кнопку Открыть платежный счёт
- Выберите валюту счёта
- Появится сообщение Счёт успешно создан
Шаги, начиная с 3-го, показаны на картинке. Только что добавленный счет вы увидите последним в списке ваших платежных счетов (7 на картинке). Нажмите на команду-ссылку напротив него, чтоб перейти к его настройкам (8 на картинке). Сообщение, которое мы получаем в ответ, выглядит вот так:
Настройка счёта ap110741100
Баланс: 0 RUB
Название магазина: Не задано
API ключ: eHW2IQZQYjlJjgQ
URL для уведомлений: Не задан
URL перехода после успешного платежа: Не задан
URL перехода после неудачи(отказа): Не задан
Плательщик комиссии при выплате: Магазин
Удалить счёт (/delapsch_100Re6)
С помощью кнопок под этим сообщением отредактируйте необходимые параметры
Создаем файл настроек
Создадим файл config.php и вставим туда следующий код
<?php $dblocation = "localhost"; $dbname = "имя базы данных mysql"; $dbuser = "пользователь базы данных mysql"; $dbpasswd = "пароль к бд mysql"; /* Подключение к серверу MySQL */ $link = mysqli_connect($dblocation,$dbuser,$dbpasswd,$dbname); if(!$link) exit("<P>Невозможно установить соединение с сервером БД.</P>" ); mysqli_query($link,"SET NAMES 'utf8'"); //апи-ключ и счёт TeleWalletAbot $tlwkey = "eHW2IQZQYjlJjgQ"; $tlwacc = "ap110741100";?>
Здесь мы подключим базу данных mysql (она нам понадобиться, чтоб хранить балансы пользователей и информацию о платежах) и заведем 2 переменные $tlwkey и $tlwacc для хранения API ключа и номера счёта из сообщения, полученного от бота.
В нашей базе данных создадим 2 таблицы:
1) users(id,name,balance,outnumber) будем хранить данные о пользователях
2) donate(id,user_id,sum,finished) информация о пополнениях
Далее создадим файл index.php (на него будем направлять наш webhook от Telegram) и вставим туда следующий код:
<?php include('vendor/autoload.php'); //подключение библиотек, загруженных через composer //классы для работы с Telegram bot api use Telegram\Bot\Api; use Telegram\Bot\Commands\Command; use Telegram\Bot\Keyboard\Keyboard; // ----------------------------------------- require_once "commands.php"; //скрипт, где мы реализуем основную логику require_once "config.php"; //файл настроек require_once "TeleWallet.php"; /*SDK Telewallet https://github.com/tlwadmin/TeleWalletSDK/blob/main/TeleWallet.php */ $telegram = new Api("токен, полученный от Telegram"); $result = $telegram -> getWebhookUpdates(); //получаем обновления $chat_id = $result["message"]["chat"]["id"]; $text = $result["message"]["text"]; $callback_query = $result['callback_query']; $data = $callback_query['data']; $chat_id_in = $callback_query['message']['chat']['id']; $uname = $result["message"]["from"]["username"]; if($chat_id>0 && $text){ //блок обработки основных команд$sm=['chat_id' => $chat_id, 'text' => $text];$ans_arr=getAnsw($text,$chat_id,$uname); for($i=0;$i<count($ans_arr);$i++){$ans=$ans_arr[$i];$reply = $ans['text'];$sm=[ 'chat_id' => $chat_id, 'text' => $reply, 'caption'=>$reply];if(array_key_exists('inline_keyboard',$ans)) {$keyboard=$ans['inline_keyboard'];$replyMarkup = json_encode($keyboard); $sm['reply_markup'] =$replyMarkup;} else if(array_key_exists('keyboard',$ans)){$keyboard=$ans['keyboard'];$reply_markup = $telegram->replyKeyboardMarkup([ 'keyboard' => $keyboard, 'resize_keyboard' => true, 'one_time_keyboard' => false ]);$sm['reply_markup']=$reply_markup;}$telegram->sendMessage($sm);} } if($data){ //блок обработки инлайн-команд$ans_arr=getAnsw($data,$chat_id_in);for($i=0;$i<count($ans_arr);$i++){$ans=$ans_arr[$i];$reply = $ans['text'];$sm=[ 'chat_id' => $chat_id_in, 'text' => $reply, 'caption'=>$reply];if(array_key_exists('inline_keyboard',$ans)) {$keyboard=$ans['inline_keyboard'];$replyMarkup = json_encode($keyboard); $sm['reply_markup'] =$replyMarkup;} else if(array_key_exists('keyboard',$ans)){$keyboard=$ans['keyboard'];$reply_markup = $telegram->replyKeyboardMarkup([ 'keyboard' => $keyboard, 'resize_keyboard' => true, 'one_time_keyboard' => false ]);$sm['reply_markup']=$reply_markup;}$telegram->sendMessage($sm);}} ?>
Здесь мы определяем, какое сообщение получено от пользователя. Отдаем его, а также идентификатор пользователя в функцию getAnsw(). Она возвращает массив сообщений, которые мы пересылаем пользователю.
Теперь создадим файл commands.php и вставим в него реализацию функции getAnsw()
<?phpfunction getAnsw($command,$chat_id, $name=""){global $link;global $telegram;global $tlwkey; global$tlwacc;$r=mysqli_query($link,"select * from users where id='$chat_id'");$ud=mysqli_fetch_assoc($r); //данные о пользователеif($command=="/start") {//добавим в бд если нетif(!$ud) mysqli_query($link,"INSERT INTO `users`(`id`,`name`) values('$chat_id','$name')");$res['text']="Привет. Я бот, позволяющий протестировать пополнение и выплату через TeleWallet";$res['keyboard']=[["Баланс","Пополнить","Выплата"]];return [$res];}if($command=="Баланс") {$res['text']="Ваш баланс: {$ud['balance']} руб";return [$res];}if($command=="Пополнить") {$res['text']="Выберите сумму, на которую хотите пополнить счёт";$res['inline_keyboard']['inline_keyboard']=[[['text'=>'1 руб','callback_data'=>'popoln_1'],['text'=>'5 руб','callback_data'=>'popoln_5'],['text'=>'10 руб','callback_data'=>'popoln_10']]];return [$res];}if($command=="Выплата") {$res['text']="Сколько вы хотите вывести?";$res['inline_keyboard']['inline_keyboard']=[[['text'=>'1 руб','callback_data'=>'vivod_1'],['text'=>'5 руб','callback_data'=>'vivod_5'],['text'=>'10 руб','callback_data'=>'vivod_10']]];addCmd("vivod_",$chat_id);return [$res];}$tlw = new TeleWallet($tlwkey,$tlwacc);if(strpos($command,'popoln_')!==false) {$arr = explode("_",$command);mysqli_query($link,"INSERT INTO `donate`( `user_id`, `sum`) values('$chat_id','{$arr[1]}')");$payId = mysqli_insert_id($link);$resp = $tlw->getСheque($arr[1],$payId);$res['text']="Вы выбрали пополнение на {$arr[1]} руб. Пополнение доступно через TeleWallet. Для продолжения нажмите кнопку под этим сообщением";$res['inline_keyboard']['inline_keyboard']=[[["text"=>"Пополнить","url"=>$resp['url']]]];return [$res];} if(strpos($command,'setnumber_')!==false) { //пользователь задает номер счета$arr = explode("_",$command);mysqli_query($link,"UPDATE `users` SET `outnumber`='{$arr[1]}' where `id`='$chat_id'");$res['text']="Номер счёта обновлен.";return [$res];}if(strpos($command,'vivod_')!==false) {$arr = explode("_",$command);if($ud['balance']<$arr[1]) $res['text']="недостаточно средств на балансе";else {if(empty($ud['outnumber']))$res['text']="У вас не задан номер счета TeleWallet для вывода. Отправьте боту setnumber_(номер ваше счета) (без скобок), чтоб задать номер счёта";else {$resp = $tlw->sendOutpay($arr[1],$ud['outnumber']);if($resp['error']==0) { //выплата удалась$res['text']="На указанный Вами номер счета выведено {$arr[1]} руб";mysqli_query($link,"UPDATE `users` SET `balance`=`balance`-{$arr[1]} where `id`='$chat_id'");}else if($resp['error']==4 || $resp['error']==5) { //выплата удалась$res['text']="Вы указали неправильный номер счёта";}else $res['text']="Выплата не удалась. Код ошибки: {$resp['error']}. Обратитесь к администратору проекта";}}return [$res];}}?>
Когда пользователь нажимает Пополнить и выбирает сумму с помощью инлайн-кнопок под сообщением, создается платежная ссылка в строке
$resp = $tlw->getСheque($arr[1],$payId);
Функция getСheque вернет ассоциативный массив с параметрами error и url. error должно быть 0, и это желательно тоже проверять, но я для краткости опустил эту проверку. Параметр url мы используем, чтоб сформировать сообщение с инлайн-кнопкой, при нажатии на которую пользователь нашего бота попадет в @TeleWalletAbot и совершит оплату (или не совершит). Проверка факта оплаты описана ниже.
Когда пользователь заказывает вывод, у него должен быть задан номер счета для вывода. Если это не так, мы сообщаем ему об этом. Если счет задан, мы пытаемся выполнить вывод, используя функцию sendOutpay, и если возвращенный ею код ошибки 0 значит вывод прошел успешно, и мы списываем средства с баланса пользователя в нашем боте.
Проверка факта оплаты
Для проверки факта оплаты и зачисления средств на баланс пользователя создадим еще один скрипт: notice.php. Вот его код:
<?phpinclude('vendor/autoload.php'); use Telegram\Bot\Api; use Telegram\Bot\Commands\Command;use Telegram\Bot\Keyboard\Keyboard; require_once "config.php";require_once "TeleWallet.php";$telegram = new Api("ключ апи вашего бота, полученный от ботфазер");$tlw = new TeleWallet($tlwkey,$tlwacc);$ri = mysqli_query($link,"SELECT * FROM `donate` WHERE `id`={$_POST['payId']}");$pay_info = mysqli_fetch_assoc($ri);if($tlw->testPayIn($_POST) && $pay_info['sum']==$_POST['sum']) {echo "YES";mysqli_query($link,"UPDATE `users` SET `balance`=`balance`+{$pay_info['sum']} where `id`={$pay_info['user_id']}"); mysqli_query($link,"UPDATE `users` SET `balance`=`balance`+{$pay_info['sum']} where `id`={$_POST['payId']}");try {$telegram->sendMessage(["text"=>"Ваш баланс пополнен на {$pay_info['sum']} руб","chat_id"=>$pay_info['user_id']]);}catch(Exception $e) {}}else echo "NO";?>
На этот файл будет прилетать вебхук от кошелька, когда пользователь успешно завершит оплату. Описание параметров POST-запроса смотрите в документации к SDK github.com/tlwadmin/TeleWalletSDK
Давайте вернемся теперь к нашему платежному счёту в кошельке. Нажмем кнопку URL для уведомлений и отправим боту ссылку на наш файл notice.php
Также укажите название магазина (точнее вашего проекта). В качестве URL успешно и URL fail просто укажите ссылку на ваш проект (бот)
Ну вот пожалуй и всё. Мы создали с вами тестового бота, который позволяет понять, как работать с платежным API TeleWallet
Посмотреть, как работает этот тестовый пример (там правда еще добавлен ручной ввод суммы и счёта при выводе) можно по ссылке: http://t.me/TlwSdkBot
Для лучшего понимания кода в статье, а также, чтоб узнать описание кодов ошибок и параметры запросов, смотрите документацию github.com/tlwadmin/TeleWalletSDK
