TunnelHunt

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

5 мин чтения

Пошаговый гайд по отладке платежных уведомлений эквайринга Т-Банка локально. Настройка адреса уведомлений, проброс через TunnelHunt и пример проверки подписи Token на Python.

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

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

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


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

Т-Банк присылает уведомления в JSON. Для проверки Token берём скалярные параметры верхнего уровня, включая Success, исключаем сам Token и вложенные объекты/массивы, добавляем пароль терминала и сортируем ключи. Булевы значения преобразуем в true/false, а не Python-строки True/False. Алгоритм описан в официальной инструкции по уведомлениям.

Используйте отдельный тестовый терминал. Пример ниже проверяет подпись и показывает статус; он не выдаёт товары и не меняет заказ в базе.

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

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

# app.py
import hashlib
import hmac
import os
from flask import Flask, request

app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 64 * 1024

# Пароль терминала из личного кабинета Т-Банка (в тестовом режиме — тестовый)
TERMINAL_PASSWORD = os.environ['TBANK_TERMINAL_PASSWORD']
TERMINAL_KEY = os.environ['TBANK_TERMINAL_KEY']

def verify_tbank_signature(json_data, password):
    if not isinstance(json_data, dict):
        return False
    received_token = json_data.get('Token')
    if (not isinstance(received_token, str) or len(received_token) != 64
            or any(c not in '0123456789abcdefABCDEF' for c in received_token)):
        return False
    params = {}
    for key, value in json_data.items():
        if key == 'Token' or isinstance(value, (dict, list)):
            continue
        if not isinstance(value, (str, bool, int)):
            return False
        params[key] = str(value).lower() if isinstance(value, bool) else str(value)
    params['Password'] = password
    signature_base = ''.join(params[k] for k in sorted(params))
    calculated_token = hashlib.sha256(signature_base.encode('utf-8')).hexdigest()
    return hmac.compare_digest(calculated_token, received_token.lower())

@app.route('/webhook/tbank', methods=['POST'])
def tbank_webhook():
    json_data = request.get_json(silent=True)
    if not isinstance(json_data, dict):
        return 'Bad Request', 400
    if (json_data.get('TerminalKey') != TERMINAL_KEY
            or not verify_tbank_signature(json_data, TERMINAL_PASSWORD)):
        return 'Invalid notification', 403
        
    print("🎉 Вебхук успешно верифицирован!")
    print(f"Статус платежа: {json_data.get('Status')}")
    print(f"Сумма платежа в копейках: {json_data.get('Amount')}")
    print(f"ID заказа: {json_data.get('OrderId')}")
    
    # Т-Банк ждет от нас текстовый ответ "OK" (чувствителен к регистру)
    return 'OK', 200

if __name__ == '__main__':
    app.run(host='127.0.0.1', port=8000, debug=False)

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

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'Flask>=3.1,<4'
export TBANK_TERMINAL_PASSWORD='ПАРОЛЬ_ТЕСТОВОГО_ТЕРМИНАЛА'
export TBANK_TERMINAL_KEY='КЛЮЧ_ТЕСТОВОГО_ТЕРМИНАЛА'
python app.py

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

В PowerShell активируйте .venv\Scripts\Activate.ps1 и задайте значения через $env:TBANK_TERMINAL_PASSWORD и $env:TBANK_TERMINAL_KEY. Пароль остаётся на сервере. Не включайте интерактивный debugger на публичном адресе.


Шаг 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. Включите получение уведомлений по HTTP(S).
  3. Укажите HTTPS-адрес обработчика в настройках уведомлений этого терминала: https://fancy-cat-456.tunnelhunt.ru/webhook/tbank
  4. Сохраните настройки и создайте тестовый платёж.

Для конкретного платежа URL также можно передать в параметре NotificationURL при инициализации: он имеет приоритет над настройкой терминала. Убедитесь, что тестовое приложение не отправляет старый NotificationURL. Интерфейс и доступные настройки сверяйте с официальной инструкцией.


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

Совершите покупку в тестовом режиме. В журнале TunnelHunt должен появиться POST, в локальной консоли — проверенный статус, в ответе — HTTP 200 с телом OK. Если это уведомление об авторизации AUTHORIZED, оно ещё не означает окончательное списание при двухстадийном платеже. Для бизнес-действия проверяйте нужный статус, свой заказ, сумму, валюту и ID платежа.

Если подпись не сходится

Ответ Что проверить
400 Запрос содержит JSON-объект, а не массив или повреждённый JSON
403 TerminalKey и пароль относятся к одному тестовому терминалу
403 при правильном пароле Success включён в строку, boolean записан строчными буквами, вложенные объекты исключены
200, но банк повторяет запрос Тело ответа точно OK, без HTML, кавычек и лишних символов
502 Локальный Flask запущен, SSH работает и пробрасывает порт 8000

При проверке не пересериализуйте весь JSON в строку для SHA-256: нужна конкатенация значений по отсортированным именам параметров. В примере допустимы строки, boolean и целые числа; некорректные скалярные типы отклоняются.


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

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

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

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

Подпись не защищает от повторной обработки уже доставленного события. В боевом коде используйте транзакцию и уникальный ключ события/состояния платежа, чтобы повтор не выдавал товар второй раз. При этом последующее изменение статуса того же PaymentId нельзя потерять из-за слишком грубой дедупликации.

Для повторяющихся тестов закрепите поддомен на Pro: URL уведомлений сохранится после переподключения, пока сам компьютер и SSH доступны. См. обзор платёжных вебхуков и повтор HTTP-запросов.

Проверьте подпись уведомления Т-Банка локально

Начните с отдельного тестового терминала и бесплатного HTTPS-туннеля. Когда подпись и ответ OK работают, закрепите адрес для следующих проверок.

Первый запуск: добавьте публичный SSH-ключ, запустите локальное приложение и команду SSH из статьи, затем откройте выданный HTTPS-адрес. Если ответа нет, пройдите проверку localhost и туннеля.

Free: 1 ГБ трафика в месяц, 1 туннель, сессия до 4 часов. Pro: 199 ₽/месяц, 50 ГБ, до 5 туннелей и резервирование поддомена. Компьютер, приложение и SSH-соединение должны работать; постоянный адрес сохраняет имя, а не доступность выключенного сервера.

Готовы запустить свой первый туннель?

Начните использовать TunnelHunt бесплатно уже сегодня и откройте доступ к локальному серверу всего одной командой.

Зарегистрироваться бесплатно →

По теме

Локальная проверка платёжного вебхука через HTTPS-туннель

Платёжные вебхуки на localhost: ЮKassa, Т-Банк, Robokassa и CloudPayments

7 сентября 2025 г.

Как проверить доставку платёжного вебхука на локальный сервер: HTTPS-туннель, выбор инструкции провайдера, подпись, повтор и диагностика HTTP-ответов.

Читать далее →
Уведомление ЮKassa через HTTPS-туннель и проверка платежа сервером

Вебхуки ЮKassa на localhost: HTTPS и проверка платежа через API

22 июня 2026 г.

Принимаем уведомления ЮKassa в локальном Flask: публичный HTTPS, проверка платежа через API, повторные события и диагностика HTTP-ответов.

Читать далее →
Проверка подписи уведомления CloudPayments на локальном сервере

CloudPayments на localhost: Content-HMAC, Pay и проверка вебхука

22 июня 2026 г.

Проверяем Pay-уведомление CloudPayments в Flask: Content-HMAC от исходного тела, form-параметры, подписанный тестовый запрос и диагностика 403.

Читать далее →
Как открыть localhost в интернете: публичный HTTPS через SSH

Как запустить localhost и открыть сайт в интернете через SSH

11 сентября 2026 г.

Запуск сайта на localhost:3000, проверка в браузере и с телефона, публичный HTTPS через SSH. Пример на Python, настройка Docker и Vite, диагностика ошибок.

Читать далее →