Налаштування прийому платежів ЮKassa в 1С-Бітрікс: обробники та 54-ФЗ

Прийом платежів через ЮKassa в 1С-Бітрікс: огляд та вартість

Уявіть: клієнт оформлює замовлення, переходить на оплату — а після успішного платежу webhook не долітає, статус замовлення не змінюється, і гроші зависають у невідомості. ЮKassa (колишня Яндекс.Каса) — один із найпопулярніших платіжних агрегаторів у Росії, але стандартний модуль із Маркетплейсу справляється не з усіма сценаріями. Ми стикалися з ситуаціями, коли не приходили сповіщення, повернення падали з помилкою, а фіскалізація видавала невалідний чек. Згідно з офіційною документацією ЮKassa, REST API версії 3 дозволяє гнучко керувати транзакціями, але вимагає акуратного налаштування. За п'ять років ми виконали понад 50 інтеграцій — від простих магазинів до B2B-платформ із десятками тисяч транзакцій щомісяця. Нижче розберемо технічні деталі та покажемо, як уникнути типових помилок.

Як працює ЮKassa технічно?

ЮKassa надає REST API (api.yookassa.ru/v3/). Схема класичного платежу:

1. Магазин відправляє POST /payments із сумою, валютою та confirmation.type=redirect — ЮKassa повертає payment.id і confirmation.confirmation_url
2. Покупець редиректиться на сторінку оплати ЮKassa
3. Після оплати ЮKassa відправляє webhook-сповіщення на return_url магазину та POST на налаштований URL сповіщень
4. Магазин викликає GET /payments/{id} для фінальної перевірки статусу

Аутентифікація — HTTP Basic: shopId:secretKey або OAuth-токен.

Підтримувані методи оплати: банківські картки, SBP, ЮMoney, SberPay, Тінькофф, QIWI (з обмеженнями), готівка через термінали. Метод передається в payment_method_type або вибирається покупцем на формі ЮKassa.

Чому варто обрати кастомну інтеграцію?

Офіційний модуль ЮKassa для Бітрікс доступний безкоштовно і підходить для стандартних магазинів. Але він має обмеження: жорстка прив'язка до стандартних компонентів, складність кастомізації статусів замовлень, відсутність гнучкої фіскалізації. Кастомний обробник вирішує ці проблеми та дозволяє інтегрувати ЮKassa з будь-якими нестандартними сутностями. Наш досвід показує, що кастомна інтеграція в 2-3 рази швидше справляється з нестандартними завданнями порівняно з доробкою готового модуля. Ми — сертифіковані спеціалісти з досвідом понад 5 років, гарантуємо коректну роботу всіх сценаріїв. Зв'яжіться з нами для оцінки вашого проекту — отримайте консультацію з інтеграції та точні терміни для вашого випадку. Вартість кастомної інтеграції обговорюється індивідуально.

Як налаштувати webhook для ЮKassa?

ЮKassa відправляє POST на налаштований URL при кожній зміні статусу платежу. У Бітрікс стандартний URL обробника: /bitrix/tools/sale_ps_result.php. Критично важливі моменти:

• Перевіряйте IP-адресу джерела. ЮKassa публікує список своїх IP: 185.71.76.0/27, 185.71.77.0/27, 77.75.153.0/25, 77.75.156.11, 77.75.156.35. Без фільтрації ви ризикуєте отримати підроблені сповіщення.
• Верифікуйте статус через API. Не довіряйте даним із webhook напряму — зробіть GET /payments/{id} для подвійної перевірки.
• Обробляйте лише термінальні статуси. pending та waiting_for_capture не вимагають зміни замовлення.

// Приклад обробки
$body = file_get_contents('php://input');
$notification = json_decode($body, true);
$payment = $client->getPaymentInfo($notification['object']['id']);
switch ($payment->getStatus()) {
    case 'succeeded':
        $bitrixPayment->setPaid('Y');
        $bitrixPayment->save();
        break;
    case 'canceled':
        // Записуємо причину відміни
        break;
}

Ключові параметри запиту

// Мінімальний запит на створення платежу через SDK
use YooKassa\Client;

$client = new Client();
$client->setAuth($shopId, $secretKey);

$payment = $client->createPayment([
    'amount' => [
        'value' => number_format($order->getPrice(), 2, '.', ''),
        'currency' => 'RUB',
    ],
    'confirmation' => [
        'type' => 'redirect',
        'return_url' => 'https://shop.ru/personal/order/detail/' . $order->getId() . '/',
    ],
    'capture' => true, // false для двостадійних платежів
    'description' => 'Замовлення №' . $order->getAccountNumber(),
    'metadata' => ['bitrix_order_id' => $order->getId()],
    'receipt' => $receiptData, // обов'язково при підключеній касі
], uniqid('', true)); // idempotency key

capture: true — одностадійний платіж, гроші списуються одразу. capture: false — двостадійний: ЮKassa холдує суму, магазин викликає POST /payments/{id}/capture при відвантаженні.

Ключ ідемпотентності (третій параметр) — обов'язковий. Без нього повторний запит при мережевій помилці створить дублюючий платіж.

Фіскалізація (54-ФЗ) і чому вона обов'язкова

Вимоги 54-ФЗ (про застосування контрольно-касової техніки) поширюються на всі онлайн-платежі. ЮKassa виступає як фіскальний реєстратор, передаючи дані в ОФД. Якщо в договорі з ЮKassa підключена передача чеків, об'єкт receipt у запиті стає обов'язковим. Без нього транзакція буде відхилена — це одна з найчастіших проблем. Структура чека повинна точно відповідати вимогам 54-ФЗ. Ми використовуємо перевірену схему з розбивкою за ставками ПДВ та ознаками предмета розрахунку. Сума всіх позицій у чеку повинна точно збігатися із сумою платежу — ЮKassa перевіряє це на своєму боці. При поверненні також потрібен чек, дзеркально відображаючий позиції. В офіційній документації ЮKassa наведені приклади структури чека, але ми адаптуємо їх під вашу специфіку.

Статуси платежу та повернення

ЮKassa підтримує часткове та повне повернення через POST /refunds. При підключеній касі повернення без чека відхиляється. Чек повернення дзеркально дублює позиції оригінального чека з типом refund. Ми реалізували понад 50 успішних інтеграцій з поверненнями, гарантуємо коректне відображення в бухгалтерії.

Тестування

ЮKassa надає тестове середовище з тими ж endpoints. У тестовому режимі (shopId=test_...) платежі проходять з тестовими картками:

• 5555555555554477 — успішна оплата
• 5555555555554444 — відмова

Обов'язково протестуйте: успішний платіж, відміну, webhook із затримкою (покупець закрив браузер до редиректу), часткове повернення. Це допоможе уникнути проблем на бойовому сайті.

Що входить в роботу та вартість

• Аудит поточної конфігурації Бітрікс та торгового каталогу
• Розробка або доробка платіжного обробника (з урахуванням 54-ФЗ)
• Налаштування webhook та обробка сповіщень
• Тестування всіх сценаріїв у тестовому середовищі
• Документація з інтеграції та інструкція для операторів
• Гарантійна підтримка 30 днів після введення в експлуатацію

Вартість інтеграції залежить від складності та обговорюється індивідуально. Кастомна інтеграція дає значну економію порівняно з наймом штатного розробника.

Терміни та як почати

Зв'яжіться з нами для оцінки вашого проекту. Отримайте консультацію з інтеграції та точні терміни для вашого випадку. Більш детальну інформацію про платіжний API можна знайти в офіційній документації ЮKassa. Про вимоги 54-ФЗ читайте в Вікіпедії.