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

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

При інтеграції платіжного шлюзу Тінькофф Каси часто стикаються з помилками генерації токена, непроходженням 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 та тестуванням у пісочниці.