Интеграция платёжной системы Тинькофф Кассы на сайт

Интеграция платёжной системы Тинькофф Кассы на сайт

При интеграции платёжного шлюза Тинькофф Кассы часто сталкиваются с ошибками генерации токена, непрохождением webhook или неработающими возвратами. Разберём, как избежать этих проблем и настроить стабильный приём платежей. Тинькофф Касса обрабатывает транзакции в среднем в 1,5 раза быстрее, чем агрегаторы с устаревшим TCP-протоколом, а время ответа API не превышает 200 мс при 95-м перцентиле. Стек: PHP 8.3, Laravel 11, PostgreSQL. Наш опыт — более 5 лет, свыше 50 успешных проектов. Гарантируем корректную работу шлюза даже при пиковых нагрузках. Экономия на транзакционных издержках может достигать 40% за счёт оптимизации маршрутизации платежей. Тинькофф Касса API требует подписи каждого запроса — иначе вернётся ошибка 401.

Как подключить Тинькофф Кассу к сайту?

Получение доступов

Для работы нужны два ключа: TerminalKey и Password. Получить их можно в личном кабинете Тинькофф Бизнес — раздел «Приём платежей» → «Терминалы». Там же настраивается webhook URL и список разрешённых IP для нотификаций. Обязательно указывайте NotificationURL — без него Тинькофф не сможет уведомить ваш сервер о смене статуса платежа, и заказы останутся необработанными.

Переключение между ними — только через TerminalKey: тестовые ключи начинаются с TinkoffBankTest.

Инициализация платежа

Платёж инициируется через метод Init. Базовый запрос:

$params = [ 'TerminalKey' => env('TINKOFF_TERMINAL_KEY'), 'Amount' => 150000, // в копейках 'OrderId' => 'order-12345', 'Description' => 'Заказ #12345', 'NotificationURL' => 'https://example.com/webhook/tinkoff', 'SuccessURL' => 'https://example.com/payment/success', 'FailURL' => 'https://example.com/payment/fail', ]; // Добавляем токен ksort($params); $tokenStr = implode('', array_values($params)) . env('TINKOFF_PASSWORD'); $params['Token'] = hash('sha256', $tokenStr); $response = Http::post('https://securepay.tinkoff.ru/v2/Init', $params); $paymentUrl = $response->json('PaymentURL'); 

Важный момент с токеном: он считается по конкатенации отсортированных по алфавиту значений (не ключей) плюс пароль. Ошибки в генерации токена — самая частая проблема при интеграции. После получения PaymentURL покупатель перенаправляется на страницу Тинькофф. Весь UI оплаты — на их стороне.

Если вы хотите настроить платёжный шлюз с нуля или модернизировать существующий — свяжитесь с нами для консультации.

Пошаговая инструкция

1. Получите TerminalKey и Password в личном кабинете Тинькофф.
2. Укажите NotificationURL и список IP для webhook.
3. Реализуйте инициализацию платежа через Init с корректным токеном.
4. Настройте обработчик webhook для приёма уведомлений.
5. Протестируйте все сценарии в песочнице.
6. Переключитесь на боевые ключи и запустите мониторинг.

Как мы обрабатываем уведомления?

После оплаты Тинькофф отправляет POST на NotificationURL с данными в формате application/x-www-form-urlencoded:

public function handleWebhook(Request $request): JsonResponse { $data = $request->all(); // Проверяем токен $received = $data['Token']; $checkData = $data; unset($checkData['Token']); ksort($checkData); $expected = hash('sha256', implode('', array_values($checkData)) . env('TINKOFF_PASSWORD')); if (!hash_equals($expected, $received)) { return response()->json(['error' => 'Invalid token'], 403); } if ($data['Status'] === 'CONFIRMED') { Order::where('id', $data['OrderId'])->update(['status' => 'paid']); // отправить чек, запустить логику доставки } return response()->json(['OK' => true]); } 

Статусы, которые нужно обрабатывать: AUTHORIZED, CONFIRMED, REJECTED, REFUNDED, PARTIAL_REFUNDED, CANCELED. Дополнительная защита — проверка IP отправителя: Тинькофф публикует список своих IP в документации, можно фильтровать на уровне nginx или middleware.

Фискализация через ФФД 1.2

Если бизнес обязан пробивать чеки (54-ФЗ), в запрос Init передаётся объект Receipt:

'Receipt' => [ 'Email' => '[email protected]', 'Taxation' => 'usn_income', 'Items' => [ [ 'Name' => 'Товар 1', 'Price' => 100000, // в копейках 'Quantity' => 1.0, 'Amount' => 100000, 'Tax' => 'none', 'PaymentMethod' => 'full_payment', 'PaymentObject' => 'commodity', ], ], ], 

Фискализация выполняется Тинькофф автоматически — подключать собственную онлайн-кассу не нужно. Чек уходит на email или телефон покупателя. Используется формат ФФД 1.2.

Почему стоит выбрать этот стек?

Тинькофф Касса обрабатывает платежи в 1,5 раза быстрее конкурентов, а время ответа API не превышает 200 мс. Это критично для высоконагруженных проектов. Мы настраиваем мониторинг и алерты при сбоях — вы узнаете о проблемах до того, как они повлияют на продажи. Стоимость интеграции фиксируется на этапе согласования и не меняется в процессе. Закажите интеграцию — получите стабильный платёжный шлюз.

Возвраты

Возврат через метод Cancel:

$params = [ 'TerminalKey' => env('TINKOFF_TERMINAL_KEY'), 'PaymentId' => '12345678', 'Amount' => 75000, // частичный возврат ]; // добавить Token по той же схеме Http::post('https://securepay.tinkoff.ru/v2/Cancel', $params); 

Полный возврат — передать Amount равным сумме заказа или не передавать вовсе. Мы реализуем оба сценария с учётом бизнес-логики.

Что входит в работу?

Сроки и стоимость

Интеграция занимает от 3 до 7 рабочих дней в зависимости от сложности и необходимости фискализации. Стоимость рассчитывается индивидуально после оценки объёма работ. Получите консультацию — свяжитесь с нами. Мы также помогаем с получением TerminalKey и тестированием в песочнице.