Локальное тестирование вебхуков Т-Банка (Т-Бизнес / Эквайринг) на localhost

Интернет-эквайринг от Т-Банка (ранее Тинькофф Эквайринг) отправляет уведомления о статусах транзакций (вебхуки) на указанный вами URL. Чтобы ваш интернет-магазин мог вовремя отгрузить товар или выслать доступы покупателю, обработчик вебхуков должен работать без сбоев.

Отладка обработчика на локальном компьютере — стандартная задача при разработке. Так как серверы Т-Банка не могут отправить запрос на localhost, мы используем TunnelHunt для создания безопасного временного HTTPS-туннеля.

---

Шаг 1: Пишем обработчик вебхуков с проверкой токена (Python / Flask)

Т-Банк присылает вебхуки в формате JSON. Чтобы убедиться, что запрос пришел именно от банка, а не от злоумышленника, Т-Банк требует проверять цифровую подпись (Token). Она вычисляется из всех присланных параметров и вашего секретного пароля терминала.

[!TIP] В macOS Monterey и выше порт 5000 занят системной службой AirPlay. Запустим локальный сервер Flask на свободном порту 8000.

Создайте файл app.py:

# app.py
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)

# Пароль терминала из личного кабинета Т-Банка (в тестовом режиме — тестовый)
TERMINAL_PASSWORD = "your_terminal_password"

def verify_tbank_signature(json_data, password):
    received_token = json_data.get('Token')
    if not received_token:
        return False
    
    # Для расчета токена исключаем сам Token и параметр Success
    params = {k: v for k, v in json_data.items() if k not in ('Token', 'Success')}
    params['Password'] = password
    
    # Сортируем ключи по алфавиту и конкатенируем значения
    sorted_keys = sorted(params.keys())
    signature_base = ''.join(str(params[k]) for k in sorted_keys)
    
    # Хешируем полученную строку через SHA-256
    calculated_token = hashlib.sha256(signature_base.encode('utf-8')).hexdigest()
    
    return calculated_token == received_token

@app.route('/webhook/tbank', methods=['POST'])
def tbank_webhook():
    if not request.is_json:
        return 'Bad Request', 400
        
    json_data = request.get_json()
    
    # Проверяем подпись вебхука
    if not verify_tbank_signature(json_data, TERMINAL_PASSWORD):
        print("🚨 Ошибка: Неверная цифровая подпись вебхука Т-Банка!")
        abort(403)
        
    print("🎉 Вебхук успешно верифицирован!")
    print(f"Статус платежа: {json_data.get('Status')}")
    print(f"Сумма платежа: {int(json_data.get('Amount', 0)) / 100} руб.")
    print(f"ID заказа: {json_data.get('OrderId')}")
    
    # Т-Банк ждет от нас текстовый ответ "OK" (чувствителен к регистру)
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=8000, debug=True)

Запустите скрипт:

pip install Flask
python app.py

Ваш локальный вебхук-приемник готов и ждет запросы на http://localhost:8000/webhook/tbank.

---

Шаг 2: Пробрасываем туннель через TunnelHunt

Сделаем локальный порт 8000 видимым для Т-Банка из интернета. Откройте новый терминал и запустите команду:

ssh -R 80:localhost:8000 -p 2222 tunnelhunt.ru

Сервер вернет временный HTTPS-адрес, например: https://fancy-cat-456.tunnelhunt.ru

Теперь Т-Банк сможет отправлять вебхуки по адресу https://fancy-cat-456.tunnelhunt.ru/webhook/tbank, а TunnelHunt перенаправит их в Flask на вашем компьютере.

---

Шаг 3: Настраиваем адрес уведомлений в Т-Банке

Для того чтобы Т-Банк отправлял уведомления:

1. Зайдите в Личный кабинет Т-Бизнес в раздел интернет-эквайринга.
2. Перейдите в Магазины → Выберите ваш магазин → Настройки.
3. Найдите блок Технические настройки (или Настройки интеграции).
4. Включите отправку уведомлений по протоколу HTTP/HTTPS.
5. Скопируйте ваш адрес из TunnelHunt и укажите его в поле URL для уведомлений (для тестирования лучше прописать его в поле Тестовый URL): https://fancy-cat-456.tunnelhunt.ru/webhook/tbank
6. Сохраните изменения.

---

Шаг 4: Тестирование и отладка

Совершите тестовую покупку на сайте. Т-Банк отправит POST-запрос с деталями операции. Скрипт проверит Token (используя заданный TERMINAL_PASSWORD), подтвердит подлинность и выведет данные транзакции прямо в вашу локальную консоль.

---

Экономия времени: Request Replay в TunnelHunt

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

Зайдите в панель управления TunnelHunt в раздел Logs:

1. Найдите запись вебхука от Т-Банка.
2. Нажмите кнопку Replay (Повторить запрос).
3. Запрос выполнится еще раз с теми же параметрами и заголовками, давая вам возможность отладить и исправить локальный код в реальном времени.