TBank (Tinkoff)

Продукт: Shelter Cloud | Уровень: Shelter | Статус: Stable

ID системы: 6 (Tinkoff) / 21 (TBankHookReceiver)

Описание

Интеграция с платёжной системой TBank (ранее Tinkoff) для приёма онлайн-платежей по картам российских банков.

Настройка в Shelter Cloud

Настройка производится в экране PrivateSettings:

UseTinkoff — включить интеграцию с Tinkoff
FrontdeskPayments_PaymentSystem = 6 — использовать Tinkoff для оплаты

Параметры учётной записи

Параметр	Описание
TerminalKey	Идентификатор терминала
Password	Пароль терминала
Taxation	Система налогообложения: `osn`, `usn_income`, `usn_income_outcome`, `envd`, `esn`, `patent`

Конфигурация сервиса (appsettings.json)

Параметр	Описание
IPWhiteList	Список разрешённых IP для callback. Доступ: отдел разработки

Системы налогообложения:

osn — общая
usn_income — упрощённая (доходы)
usn_income_outcome — упрощённая (доходы минус расходы)
envd — ЕНВД
esn — ЕСН
patent — патентная

API Endpoints

Среда	URL
Production	`https://securepay.tinkoff.ru/html/payForm/payform.html`

Callback

Параметр	Значение
URL	`https://cloud.shelter.ru/Tinkoff/Callback`
Метод	POST
Формат	JSON

Мониторинг (Zabbix)

Проверка	URL
Доступность	`GET https://cloud.shelter.ru/Tinkoff/`

Должен возвращать HTTP 200 без авторизации.

Логирование

Все события логируются в Graylog (channel: Tinkoff).

Примеры сообщений при callback

Успешная оплата:

Success payment: 12345

Ошибка подписи:

Error payment: Sign not valid

OrderId не валиден:

Error payment: OrderId not valid

Данные не найдены:

Error payment: Reservation data with cashId 12345 not found

Алгоритм подписи

Подпись callback: SHA256

1. Извлечь все поля из callback, кроме: Receipt, Data, Token
2. Преобразовать boolean в lowercase ("true"/"false")
3. Добавить поле Password
4. Отсортировать поля по имени (алфавитно)
5. Конкатенировать значения
6. Вычислить SHA256 hash
7. Сравнить с полем Token (case-insensitive)

Процесс оплаты

1. Клиент нажимает «Оплатить» в виджете бронирования
2. Система формирует данные для Tinkoff Pay Form
3. Клиент перенаправляется на securepay.tinkoff.ru
4. После оплаты Tinkoff отправляет callback
5. Система проверяет подпись и сохраняет платёж

Поддерживаемые валюты

Код	Валюта
RUB	Российский рубль

Фискализация

Поддерживается отправка фискальных чеков по 54-ФЗ через Tinkoff.

Параметры чека:

Email / Phone — контакт клиента
Taxation — система налогообложения
Items — список позиций с НДС

Устранение неполадок

Ошибка «Sign not valid»

Решение:

Проверьте правильность пароля (Password)
Убедитесь, что CheckSignature включён только в production
Проверьте логи

Callback не приходит