Інтеграція платіїної системи Тінькофф Касса на сайт
Тінькофф Касса — один з найбільш поширених платіжних шлюзів на російському ринку. Підтримує карти Visa, Mastercard, МІР, СБП, Apple Pay, Google Pay та рассрочку через «Тінькофф Рассрочку». Офіційний SDK є для PHP, Java, .NET, Python та Node.js, але більшість інтеграцій здійснюється прямо через REST API.
Підключення та отримання доступів
Два ключа необхідні: TerminalKey та Password. Отримати їх можна в особистому кабінеті Тінькофф Бізнес — розділ «Прийм платежів» → «Терміналі». Там же налаштовується сповіщення про оплату (webhook URL) та список дозволених IP.
Тестове середовище: https://rest-api-test.tinkoff.ru/v2/
Боевое середовище: https://securepay.tinkoff.ru/v2/
Переключення між ними — тільки через 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 оплати — на їх стороні.
Webhook та перевірка статусу
Після оплати Тінькофф відправляє 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 або телефон покупця.
Повернення
Повернення через метод Cancel:
$params = [
'TerminalKey' => env('TINKOFF_TERMINAL_KEY'),
'PaymentId' => '12345678',
'Amount' => 75000, // частинковий повернення
];
// додати Token по тій же схемі
Http::post('https://securepay.tinkoff.ru/v2/Cancel', $params);
Повне повернення — передати Amount рівним сумі замовлення або не передавати взагалі.
Часові терміни та особливості
Тестування та здача інтеграції у Тінькофф займає близько 2–3 робочих днів: потрібно провести кілька тестових транзакцій, після чого менеджер активує боевий термінал. Для фіскалізації термін збільшується: потрібно узгодити налаштування касс. На практиці повний цикл від отримання доступів до першого реального платежу — 5–7 робочих днів.