Курс

Тинькофф: подключаем за 10 минут

МОДУЛЬ 7: ПРИЁМ ОПЛАТ • Урок 5 из 6

Тинькофф (T-Pay, Тинькофф Эквайринг) — это то, что мы реально используем на NeuroKod. Не теория, не "попробуй когда-нибудь", а рабочая система, которая прямо сейчас принимает деньги на этом сайте. В этом уроке Claude подключит Тинькофф к твоему проекту. Ты делаешь только то, что нельзя автоматизировать: регистрируешь бизнес-аккаунт и копируешь ключи. Всё остальное — код, серверную часть, webhook, тестирование — Claude сделает сам.

[ ПОЧЕМУ ТИНЬКОФФ ]

Тинькофф Эквайринг — одна из самых популярных платёжных систем в России. Работает через API, без виджетов и iframe (которые часто глючат).

[+] Плюсы:

  • Работает с ИП и самозанятыми (не только ООО)
  • Все российские карты (Visa, Mastercard, МИР)
  • СБП — моментальная оплата через мобильный банк
  • Простой REST API — не нужно ставить SDK, просто HTTP-запросы
  • Тестовый режим — можно проверить всё до подключения боевого аккаунта
  • Автоматические чеки по 54-ФЗ (фискализация встроена)
  • Низкие комиссии (от 1.5%, зависит от оборота)

[-] Минусы:

  • Нужен статус ИП или самозанятого (физлица не подключат)
  • Модерация 1-3 дня
  • API документация местами запутанная (но Claude знает все нюансы)
💡 ИЗ ПРАКТИКИ:

На NeuroKod мы пробовали виджет Тинькофф (Tinkoff Pay Widget) — он вставляется как <script> на страницу. Звучит удобно, но на практике он конфликтовал с CSP, не грузился через Vercel WAF, и вообще вёл себя непредсказуемо. Переделали на прямые API-вызовы — и всё заработало. В этом уроке мы делаем именно так: сервер вызывает API Тинькофф напрямую, без виджетов.

[ ШАГ 1: РЕГИСТРАЦИЯ — ТЫ ДЕЛАЕШЬ САМ ]

Это единственная часть, которую Claude не может сделать за тебя. Нужен живой человек с документами.

Что нужно:

  • ИП или самозанятый (или ООО)
  • ИНН
  • Расчётный счёт в Тинькофф (или в любом другом банке)

Как зарегистрироваться:

  1. Открой t-bank.ru (бывший tinkoff.ru)
  2. Найди раздел "Эквайринг" или "Интернет-эквайринг"
  3. Нажми "Подключить"
  4. Заполни форму:
    • Тип бизнеса (ИП / самозанятый / ООО)
    • ИНН
    • Описание того, что продаёшь (напиши "онлайн-курсы" или "цифровые товары")
    • URL сайта
  5. Дождись одобрения (1-3 рабочих дня)

После одобрения ты получишь доступ к Личному кабинету мерчанта.

⚠️ ВАЖНО:

Если у тебя ещё нет ИП — оформи. Для продажи онлайн-курсов это обязательно. Claude поможет разобраться с документами, если спросишь. Но регистрацию ИП делаешь сам (или через сервис типа "Моё дело").

[ ШАГ 2: ПОЛУЧАЕМ КЛЮЧИ — ТЫ ДЕЛАЕШЬ САМ ]

После одобрения заявки тебе нужно найти два значения в Личном кабинете:

  1. Открой Личный кабинет мерчанта
  2. Перейди в Магазины → Твой магазин → Терминалы
  3. Найди:
    • TerminalKey — идентификатор терминала (выглядит как: 1234567890ABCDEF)
    • Password — пароль терминала (выглядит как: o8i7v4x3nz5ka6lq)

Сохрани эти два значения — они понадобятся на следующем шаге.

⚠️ ВАЖНО:

Password — это НЕ пароль от личного кабинета. Это специальный пароль терминала, который используется для подписи запросов к API. Его можно найти только в настройках терминала. Никому не показывай!

[ ШАГ 3: ТЕСТОВЫЙ РЕЖИМ ]

Тинькофф даёт тестовый терминал для проверки интеграции. Тестовые ключи работают на отдельном URL (rest-api-test.tinkoff.ru) и не списывают реальные деньги.

Тестовые данные:

  • Тестовый TerminalKey и Password выдаются в Личном кабинете (раздел "Тестовый терминал")
  • Либо используй демо-терминал из документации Тинькофф

Тестовые карты:

Карта Результат
4300 0000 0000 0777 Успешная оплата (CVC: 111)
4300 0000 0000 0044 Отклонённая оплата
4000 0000 0000 0002 Оплата с 3DS

Срок действия: любая дата в будущем. CVC: любые 3 цифры (для первой карты — 111).

💡 СОВЕТ:

Сначала всё настрой на тестовых ключах, убедись что работает, а потом переключи на боевые. Это бесплатно и безопасно.

[ ШАГ 4: CLAUDE НАСТРАИВАЕТ СЕРВЕР ]

Вот тут начинается магия. Ты отправляешь Claude промпт, и он создаёт весь серверный код.

Попроси Claude Code:

"У меня есть VDS (Ubuntu) с Node.js сервером на Express.
Мне нужно подключить Тинькофф Эквайринг для приёма оплаты.

Вот мои данные:
- TerminalKey: [ВСТАВЬ СВОЙ]
- Password: [ВСТАВЬ СВОЙ]
- Сайт: https://[твой-домен]

Сделай:
1. Добавь TINKOFF_TERMINAL_KEY, TINKOFF_PASSWORD и TINKOFF_TEST_MODE=true в файл .env на сервере
2. Создай API маршрут POST /api/init-payment который:
- Принимает tariff, userId, email
- Генерирует OrderId
- Рассчитывает сумму (цену укажи: 4990 руб за полный пакет)
- Формирует Token по алгоритму Тинькофф (SHA-256 от отсортированных значений + Password)
- Вызывает Тинькофф API /v2/Init
- Возвращает PaymentURL для редиректа клиента
- Добавь Receipt для фискализации (54-ФЗ): Taxation=usn_income, PaymentMethod=full_payment, PaymentObject=service
3. Создай POST /api/webhook для обработки уведомлений от Тинькофф:
- Проверяй Token (подпись) — алгоритм такой же как для Init
- При статусе CONFIRMED — сохраняй покупку в Supabase (таблица purchases)
- Всегда возвращай HTTP 200 (иначе Тинькофф будет повторять запросы)
4. Добавь SuccessURL и FailURL (страницы после оплаты)
5. Добавь NotificationURL = https://[мой-домен]/api/webhook

Используй fetch (встроен в Node.js 18+), без сторонних библиотек.
Сервер работает через Nginx reverse proxy.

ВАЖНО: перед началом загугли актуальную документацию Тинькофф Эквайринг API."

Что сделает Claude:

  • Добавит ключи в .env на сервере
  • Создаст маршрут /api/init-payment — создание платежа
  • Создаст маршрут /api/webhook — обработка оплаты
  • Реализует алгоритм Token (подпись) по документации Тинькофф
  • Добавит Receipt для автоматической фискализации
  • Перезапустит сервер (PM2)

[ ШАГ 5: CLAUDE СОЗДАЁТ СТРАНИЦУ ОПЛАТЫ ]

Теперь нужна кнопка "Купить" на сайте. Попроси Claude:

"Создай страницу оплаты (purchase.html) для моего сайта.

Требования:
1. Страница с описанием тарифа и кнопкой 'Получить доступ'
2. При нажатии на кнопку:
- Проверить что пользователь авторизован (используй Auth.isLoggedIn())
- Если не авторизован — редирект на auth.html
- Если уже оплачено — редирект на courses.html
- Отправить POST /api/init-payment с tariff, userId, email
- Получить paymentUrl и сделать редирект на страницу оплаты Тинькофф
3. Создай также payment-success.html и payment-fail.html

Стиль: тёмная тема, Inter шрифт, файл styles.css уже есть."

Что сделает Claude:

  • Создаст purchase.html с кнопкой оплаты
  • Напишет скрипт, который вызывает /api/init-payment и редиректит на Тинькофф
  • Создаст страницы успеха и ошибки

[ ШАГ 6: НАСТРОЙКА WEBHOOK — ТЫ ДЕЛАЕШЬ САМ ]

Webhook — это URL, на который Тинькофф пришлёт уведомление когда клиент оплатит. Claude уже создал обработчик (POST /api/webhook), но нужно указать этот URL в Личном кабинете Тинькофф.

  1. Открой Личный кабинет мерчанта
  2. Перейди в Магазины → Терминалы → Настройки
  3. Найди поле Notification URL (или "URL для уведомлений")
  4. Укажи: https://твой-домен.ru/api/webhook
  5. Сохрани
⚠️ ВАЖНО:

URL webhook должен быть HTTPS. Если у тебя ещё нет SSL-сертификата, попроси Claude настроить Let's Encrypt (Certbot). Без HTTPS Тинькофф не будет отправлять уведомления.

[ ШАГ 7: ТЕСТИРОВАНИЕ ]

Всё настроено. Проверяем.

Попроси Claude:

"Протестируй интеграцию Тинькофф на моём сервере:
1. Проверь что /api/health отдаёт tinkoff: 'configured'
2. Сделай тестовый запрос к /api/init-payment и покажи результат
3. Проверь что PaymentURL открывается
4. Проверь логи PM2 на ошибки

Сервер: [IP] или ssh [user]@[IP]"

Что проверить руками:

  1. Открой свой сайт → нажми "Купить"
  2. Откроется страница Тинькофф (тестовая)
  3. Введи тестовую карту: 4300 0000 0000 0777 (CVC: 111, дата: любая в будущем)
  4. Нажми "Оплатить"
  5. Тебя перекинет на payment-success.html
  6. Проверь в Supabase (Studio) что в таблице purchases появилась новая запись

[ ШАГ 8: БОЕВОЙ РЕЖИМ ]

Когда тестирование пройдено — переключаемся на реальные платежи.

Что делаешь ты:

  1. В Личном кабинете Тинькофф получи боевые TerminalKey и Password
  2. Убедись что Notification URL указан для боевого терминала тоже

Попроси Claude:

"Переключи Тинькофф с тестового режима на боевой:
1. Замени TINKOFF_TERMINAL_KEY и TINKOFF_PASSWORD в .env на боевые: [вставь ключи]
2. Поставь TINKOFF_TEST_MODE=false (или удали)
3. Перезапусти сервер
4. Проверь /api/health — должно показать tinkoffMode: 'PRODUCTION'"

[ КАК ЭТО РАБОТАЕТ ]

Клиент нажимает "Купить"
        ↓
Браузер отправляет POST /api/init-payment
        ↓
Твой сервер (Node.js)
        ↓
Формирует Token + вызывает Тинькофф API /v2/Init
        ↓
Тинькофф возвращает PaymentURL
        ↓
Сервер отдаёт PaymentURL браузеру
        ↓
Браузер редиректит клиента на страницу оплаты Тинькофф
        ↓
Клиент вводит карту и оплачивает
        ↓
Тинькофф отправляет POST /api/webhook на твой сервер
        ↓
Сервер проверяет подпись (Token) → сохраняет покупку в Supabase
        ↓
Клиент видит payment-success.html

Весь код работает на твоём сервере. Никаких виджетов, iframe, сторонних скриптов на странице. Тинькофф видит только API-запросы с российского IP — никаких блокировок WAF.

[ ЧАСТЫЕ ПРОБЛЕМЫ ]

1. "Тинькофф возвращает ошибку 99 или HTML вместо JSON"

Причина: запрос идёт с иностранного IP (Vercel, Cloudflare) и блокируется WAF Тинькофф.

Решение:

  • Сервер должен быть на российском VDS
  • Тинькофф API вызывается с сервера, НЕ из браузера

2. "Webhook не приходит"

Причина: URL не указан или нет HTTPS.

Решение:

  • Проверь Notification URL в Личном кабинете Тинькофф
  • URL должен быть https:// (не http)
  • Сервер должен отвечать 200 OK — если вернёшь ошибку, Тинькофф перестанет слать

3. "Token не совпадает (Invalid signature)"

Причина: неправильно реализован алгоритм генерации Token.

Решение: попроси Claude перепроверить:

"Webhook от Тинькофф возвращает Invalid signature.
Проверь алгоритм генерации Token:
1. Берём все поля из уведомления (кроме Token и вложенных объектов)
2. Добавляем Password
3. Сортируем по ключу (алфавитно)
4. Склеиваем значения в одну строку
5. SHA-256 хеш
Покажи промежуточные значения для отладки."

4. "Оплата прошла, но доступ не появился"

Причина: webhook не обработался или ошибка записи в Supabase.

Решение:

"Проверь логи webhook на сервере:
1. Покажи логи PM2 за последний час (pm2 logs --lines 100)
2. Проверь таблицу purchases в Supabase — есть ли запись для этого платежа?
3. Если записи нет — проверь что SUPABASE_SERVICE_KEY в .env правильный"

[ ЧЕКЛИСТ ГОТОВНОСТИ ]

  • Зарегистрирован в Тинькофф Эквайринг (ИП / самозанятый / ООО)
  • Получены TerminalKey и Password из Личного кабинета
  • Claude создал серверный код (init-payment + webhook)
  • Ключи добавлены в .env на сервере
  • Создана страница оплаты (purchase.html)
  • Notification URL указан в настройках терминала Тинькофф
  • Протестировано тестовой картой → запись в Supabase → страница успеха
  • Переключено на боевой режим (TINKOFF_TEST_MODE=false)
  • Первая реальная оплата прошла
💬 Совет:

Тинькофф — это то, на чём реально работает NeuroKod. Не виджет, не iframe — прямые API-вызовы с российского сервера. Три промпта Claude — и у тебя работающий приём оплаты. Буквально 10 минут, если ключи уже есть. А если нет — иди регистрируй ИП, это тоже 10 минут (но в налоговой).