Доброго времени суток.

Сегодня хочу рассказать о том, как работать с платежным 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 таблицы:

users(id,name,balance,outnumber) — будем хранить данные о пользователях
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()

<?php
function 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. Вот его код:

<?php
include('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.

Давайте вернемся теперь к нашему платежному счёту в кошельке. Нажмем кнопку URL для уведомлений и отправим боту ссылку на наш файл notice.php

Также укажите название магазина (точнее вашего проекта). В качестве URL успешно и URL fail просто укажите ссылку на ваш проект (бот)

Ну вот пожалуй и всё. Мы создали с вами тестового бота, который позволяет понять, как работать с платежным API TeleWallet.

Посмотреть, как работает этот тестовый пример (там правда еще добавлен ручной ввод суммы и счёта при выводе) можно по ссылке: http://t.me/TlwSdkBot.

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

Подключение автоплатежей через TeleWalletAbot к своему Telegram-боту