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

Интернет-эквайринг от Т-Банка (ранее Тинькофф Эквайринг) отправляет уведомления о статусах транзакций (вебхуки) на указанный вами 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: Настраиваем адрес уведомлений в Т-Банке
Для того чтобы Т-Банк отправлял уведомления:
- Зайдите в кабинет интернет-эквайринга, откройте Магазины → Терминалы и выберите настройку отдельного тестового терминала.
- Включите получение уведомлений по HTTP(S).
- Укажите HTTPS-адрес обработчика в настройках уведомлений этого терминала:
https://fancy-cat-456.tunnelhunt.ru/webhook/tbank - Сохраните настройки и создайте тестовый платёж.
Для конкретного платежа 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:
- Найдите запись вебхука от Т-Банка.
- Нажмите кнопку Replay (Повторить запрос).
- Запрос выполнится еще раз с теми же параметрами и заголовками, давая вам возможность отладить и исправить локальный код в реальном времени.
Подпись не защищает от повторной обработки уже доставленного события. В боевом коде используйте транзакцию и уникальный ключ события/состояния платежа, чтобы повтор не выдавал товар второй раз. При этом последующее изменение статуса того же PaymentId нельзя потерять из-за слишком грубой дедупликации.
Для повторяющихся тестов закрепите поддомен на Pro: URL уведомлений сохранится после переподключения, пока сам компьютер и SSH доступны. См. обзор платёжных вебхуков и повтор HTTP-запросов.
Проверьте подпись уведомления Т-Банка локально
Начните с отдельного тестового терминала и бесплатного HTTPS-туннеля. Когда подпись и ответ OK работают, закрепите адрес для следующих проверок.
Первый запуск: добавьте публичный SSH-ключ, запустите локальное приложение и команду SSH из статьи, затем откройте выданный HTTPS-адрес. Если ответа нет, пройдите проверку localhost и туннеля.
Free: 1 ГБ трафика в месяц, 1 туннель, сессия до 4 часов. Pro: 199 ₽/месяц, 50 ГБ, до 5 туннелей и резервирование поддомена. Компьютер, приложение и SSH-соединение должны работать; постоянный адрес сохраняет имя, а не доступность выключенного сервера.
Готовы запустить свой первый туннель?
Начните использовать TunnelHunt бесплатно уже сегодня и откройте доступ к локальному серверу всего одной командой.
Зарегистрироваться бесплатно →По теме

Платёжные вебхуки на localhost: ЮKassa, Т-Банк, Robokassa и CloudPayments
7 сентября 2025 г.
Как проверить доставку платёжного вебхука на локальный сервер: HTTPS-туннель, выбор инструкции провайдера, подпись, повтор и диагностика HTTP-ответов.

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

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

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