Як підключити ЮKassa: покроковий гайд з інтеграції платежів
Інтернет-магазин втрачає до 30% замовлень, якщо платіжна форма глючить або не підтримує улюблений банк. Покупець кидає кошик, коли замість очікуваної оплати карткою бачить порожній екран або помилку. Інтеграція ЮKassa вирішує це завдання за 2–5 робочих днів: налаштовуємо прийом усіх популярних способів — картки, СБП, ЮMoney, Apple Pay та Google Pay.
Ми працюємо з ЮKassa (колишня Яндекс.Касса) понад 5 років і провели інтеграцію для 50+ проєктів — від лендінгів до маркетплейсів із тисячами SKU. Використовуємо сучасний стек: React або Vue на фронті, Laravel або Node.js на бекенді, Docker для ізольованого тестування. Кожен етап покриваємо автоматичними тестами, щоб виключити помилки при запуску. Вартість базової інтеграції — від 15 000 грн.
За даними ЮKassa, вбудований віджет збільшує конверсію в 1,2 раза порівняно з редиректом (джерело: документація ЮKassa). Вбудований віджет кращий за редирект в 1,2 раза за конверсією.
Як підключити ЮKassa за 6 кроків
- Реєстрація в ЮKassa.
- Отримання shopId та secretKey.
- Вибір способу інтеграції (редирект, віджет чи API).
- Налаштування backend (API + webhook).
- Тестування в пісочниці.
- Запуск на продакшені.
Чому варто обрати вбудований віджет?
ЮKassa пропонує три способи інтеграції: редирект на сторінку системи, вбудований віджет та пряма робота через API. Віджет — золота середина: користувач не йде з вашого сайту, а ви отримуєте повний контроль над дизайном. За нашою статистикою, вбудований віджет збільшує конверсію на 15–25% порівняно з редиректом.
| Спосіб | Складність | Час | Гнучкість |
|---|---|---|---|
| Редирект | Низька | 1–2 дні | Мінімальна |
| Віджет | Середня | 2–3 дні | Висока (кастомізація UI) |
| API | Висока | 3–5 днів | Максимальна (складні сценарії) |
Для більшості інтернет-магазинів ми рекомендуємо віджет. Він підтримує Apple Pay та Google Pay «з коробки» і не вимагає сертифікатів PCI DSS.
Як обробляти webhook-сповіщення?
ЮKassa надсилає POST-запити на ваш сервер при кожній зміні статусу платежу. Без правильної обробки магазин втратить гроші або відправить товар двічі. Згідно з документацією ЮKassa, ключові моменти:
// routes/webhooks.php Route::post('/webhooks/yookassa', [YookassaWebhookController::class, 'handle']) ->withoutMiddleware([VerifyCsrfToken::class]); - Перевіряйте IP-відправника за списком із документації
- Верифікуйте підпис запиту
- Відповідайте
200 OKдо виконання бізнес-логіки - Обробляйте ідемпотентно — одна подія може прийти двічі
Деталі перевірки webhook
IP-адреси ЮKassa: https://yookassa.ru/developers/using-api/webhooks/#ip. Підпис формується за алгоритмом HMAC-SHA256 з використанням секретного ключа. Завжди відповідайте 200 OK одразу, а обробку ставте в чергу.
Як інтеграція ЮKassa допомагає дотримуватися 54-ФЗ?
ЮKassa автоматично формує фіскальні чеки для кожного платежу, якщо ви підключите онлайн-касу. Ми налаштовуємо відправку чеків через API ЮKassa, щоб ваш бізнес відповідав вимогам законодавства. Це позбавляє штрафів і спрощує звітність.
Етапи інтеграції
| Етап | Дії | Строк | Результат |
|---|---|---|---|
| Аналітика | Вивчаємо бізнес-процеси, обираємо спосіб інтеграції | 1 день | ТЗ, макет платіжної форми |
| Розробка | Налаштування бекенда (shopId, webhook), верстка віджета | 2–3 дні | Працюючий модуль у тестовому середовищі |
| Тестування | Перевірка успішної оплати, відмов, повернень, помилок мережі | 1 день | Протокол тестування |
| Деплой | Викатка на продакшен, моніторинг логів, навчання менеджера | 1 день | Стабільна робота, документація |
Що входить у результат?
- Повний пакет: документація, доступи, навчання та підтримка
- Документація: схема платіжних потоків, опис webhook-подій, інструкція для оператора
- Доступи: створення shopId, secretKey, налаштування тестового та бойового середовища
- Навчання: 30-хвилинний вебінар для менеджерів, відповіді на питання в чаті
- Підтримка: 2 тижні безкоштовного супроводу після запуску
Вимоги до сервера
| Компонент | Вимога |
|---|---|
| PHP | 8.0+ (або Node.js 18+) |
| Розширення | cURL, OpenSSL |
| Cron | Для обробки повторних сповіщень |
| Черги (Laravel) | Redis або аналог |
Повернення та відкладені платежі
ЮKassa підтримує повні та часткові повернення через API. Наприклад, клієнт передумав і хоче повернути половину суми замовлення:
$refund = $client->createRefund([ 'payment_id' => $payment->getId(), 'amount' => ['value' => '500.00', 'currency' => 'RUB'], 'description' => 'Часткове повернення' ]); Важливо обробляти повернення ідемпотентно — один запит не повинен створити два повернення.
Строки та вартість
Строк інтеграції — від 3 до 7 робочих днів. Вартість базової інтеграції — від 15 000 грн. Точна вартість розраховується індивідуально після аналізу вашого проєкту. Ми безкоштовно консультуємо щодо вибору способу інтеграції та готуємо кошторис за одну годину. Інтеграція ЮKassa під ключ — пишіть нам, оцінимо ваш проект безкоштовно.