Інтеграція платіжної системи Тінькофф Каси на сайт

При інтеграції платіжного шлюзу Тінькофф Каси часто стикаються з помилками генерації токена, непроходженням webhook або непрацюючими поверненнями. Розберемо, як уникнути цих проблем і налаштувати стабільний прийом платежів. Тінькофф Каса обробляє транзакції в середньому в 1,5 раза швидше, ніж агрегатори з застарілим TCP-протоколом, а час відповіді API не перевищує 200 мс при 95-му перцентилі. Стек: PHP 8.3, Laravel 11, PostgreSQL. Наш досвід — понад 5 років, більше 50 успішних проєктів. Гарантуємо коректну роботу шлюзу навіть при пікових навантаженнях (до 10 000 запитів на хвилину). Економія на транзакційних витратах може сягати 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 оплати — на їхньому боці.

Якщо ви хочете налаштувати платіжний шлюз з нуля або модернізувати існуючий — зв'яжіться з нами для консультації. Вартість базової інтеграції — від 15 000 грн.

Покрокова інструкція

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

Переваги інтеграції Тінькофф Каси на сайт

Ми забезпечуємо стабільність роботи з аптаймом 99,9% та середнім часом відповіді API 150 мс. Завдяки оптимізації, вартість транзакцій знижується на 30-40% порівняно з іншими агрегаторами. Наша команда має 5+ років досвіду та реалізувала 50+ успішних проєктів.

Як ми обробляємо повідомлення?

Після оплати Тінькофф надсилає 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 та тестуванням у пісочниці.