Інтеграція 1С-Бітрікс з платіжною системою Тінькофф Оплата

Інтеграція 1С-Бітрікс із платіжною системою Тінькофф Оплата

Тінькофф Оплата — це не Тінькофф Кредит і не Тінькофф Pay. Три різних продукти, три різних API, і плутанина між ними — стандартна помилка при первинному налаштуванні. Тінькофф Оплата (вона ж «Інтернет-еквайринг Тінькофф») — повноцінний платіжний шлюз для прийому карткових платежів, що працює через API securepay.tinkoff.ru/v2/. Саме про нього йтиметься.

Архітектура шлюзу Тінькофф

API Тінькофф побудовано за схемою Init → Pay → Confirm/Cancel. Основні методи:

• Init — ініціалізація платежу, отримання PaymentURL і PaymentId
• GetState — отримання актуального статусу транзакції
• Confirm — підтвердження преавторизованого платежу
• Cancel — скасування платежу або повернення
• Charge — рекурентне списання по прив'язаній картці

Всі запити підписуються токеном — SHA-256 від конкатенації значень параметрів і пароля в алфавітному порядку ключів. Неправильний порядок при генерації токена — найпоширеніша причина помилки INVALID_SIGNATURE при першому запуску.

Інтеграція з модулем sale Бітрікс

Тінькофф має офіційний модуль для Бітрікс на Маркетплейсі. Альтернативно — кастомний обробник у /local/php_interface/include/sale_payment/tinkoff_acquiring/.

Структура обробника:

handler.php         — основний клас, успадковує ServiceHandler
.description.php    — опис і іконка
.settings.php       — поля: TerminalKey, Password, TestMode, TwoStagePayment
template/           — шаблон кнопки оплати

Метод initiatePay формує запит до Init:

$request = [
    'TerminalKey' => $terminalKey,
    'Amount'      => $payment->getSum() * 100, // в копійках
    'OrderId'     => $payment->getOrderId(),
    'Description' => 'Замовлення №' . $order->getField('ACCOUNT_NUMBER'),
    'SuccessURL'  => $returnUrl,
    'FailURL'     => $failUrl,
    'NotificationURL' => $notifyUrl,
    'Receipt'     => $this->buildReceipt($order), // для 54-ФЗ
];

Нотифікації та обробка статусів

Тінькофф надсилає POST на NotificationURL при кожній зміні статусу. Статуси, що вимагають дій у Бітрікс:

Нотифікація містить Token для верифікації підпису — перевірку обов'язково реалізовувати. Після успішної обробки повертати рядок OK, інакше Тінькофф повторить спробу.

Чекові дані для 54-ФЗ

Тінькофф має вбудовану онлайн-касу. При передачі об'єкта Receipt у запит Init каса формує чек автоматично. Структура Receipt:

{
  "Email": "[email protected]",
  "Phone": "+79001234567",
  "Taxation": "osn",
  "Items": [
    {
      "Name": "Назва товару",
      "Price": 150000,
      "Quantity": 2,
      "Amount": 300000,
      "Tax": "vat20",
      "PaymentMethod": "full_payment",
      "PaymentObject": "commodity"
    }
  ]
}

Дані товарів беруться з кошика замовлення: $order->getBasket()->getOrderableItems(). Для кожної позиції потрібно зіставити ставку ПДВ із каталогу з кодом Tax в API Тінькофф (vat0, vat10, vat20, none).

Рекурентні платежі

Тінькофф підтримує прив'язку картки при першому платежі (параметр Recurrent: Y в Init) і подальші списання методом Charge без участі покупця. У Бітрікс це використовується для підписок: при оформленні підписки зберігається RebillId з нотифікації, потім по крону викликається Charge з потрібним Amount. Детальніше — у статті про рекурентні платежі.

Реальний кейс: таймаут при високому навантаженні

Маркетплейс одягу, навантаження ~500 замовлень на день. Періодично покупці скаржилися, що після оплати потрапляли на сторінку «Помилка», хоча гроші списалися. Діагностика: при пікових навантаженнях обробник SuccessURL встигав викликати GetState раніше, ніж Тінькофф завершував проводку — статус повертався AUTHORIZED замість CONFIRMED. Статус замовлення не змінювався, покупець бачив помилку. Рішення: на SuccessURL показувати проміжну сторінку «Платіж обробляється» з JS-поллінгом статусу через власний AJAX-ендпоінт, а підтвердження оплати робити виключно по нотифікації.

Тестування

У особистому кабінеті Тінькофф (merchant.tinkoff.ru) створюється тестовий термінал з окремим TerminalKey. Тестові картки для різних сценаріїв (успіх, відмова, 3DS) — у документації API. Перед виходом у прод обов'язково перевірити: підпис нотифікацій, коректність суми в копійках, формування Receipt, обробку подвійного callback.

Терміни: базове підключення без каси — 1–3 дні. З 54-ФЗ і кастомною логікою статусів — 3–6 робочих днів.