Інтеграція платіжної системи ЮKassa на сайт

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

ЮКаса — один з основних платіжних шлюзів для російських інтернет-магазинів. Приймає карти, ЮMoney, СБП, Apple Pay, Google Pay, оплату готівкою через терміналиналі. Підходить для фізичних осіб-ІП, ООО, самозайнятих. Інтеграція через REST API або готовий SDK.

Варіанти інтеграції

Перенаправлення (хостингова форма) — покупець перенаправляється на сторінку ЮКаси. Мінімум коду, максимум безпеки — дані карти вводяться на стороні платіжної системи. Підходить для більшості магазинів.

Вбудований віджет — JavaScript-віджет вбудовується на сторінку оформлення замовлення. Покупець не покидає сайт, але дані карти все одно обробляє ЮКаса. Потребує payment_token з бекенду.

API-інтеграція — повний контроль через REST API. Потрібна для нестандартних сценаріїв: відкладені платежі, утримання, маркетплейсні спліти.

Базова реалізація (PHP/Laravel)

// composer require yookassa/yookassa-sdk-php

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

$payment = $client->createPayment([
    'amount' => ['value' => '1500.00', 'currency' => 'RUB'],
    'confirmation' => [
        'type' => 'redirect',
        'return_url' => route('payment.success', $order->id)
    ],
    'capture' => true,
    'description' => "Заказ #{$order->id}",
    'metadata' => ['order_id' => $order->id]
]);

$confirmationUrl = $payment->getConfirmation()->getConfirmationUrl();

Webhook-обробка

ЮКаса відправляє сповіщення на вказаний URL при зміні статусу платежу. Важливо:

• Перевіряти IP-адресу відправника (список IP ЮКаси публікує в документації)
• Верифікувати підпис запиту
• Відповідати 200 OK до виконання бізнес-логіки (інакше повторна відправка)
• Обробляти ідемпотентно — одна й та ж подія може прийти двічі

// routes/webhooks.php
Route::post('/webhooks/yookassa', [YookassaWebhookController::class, 'handle'])
     ->withoutMiddleware([VerifyCsrfToken::class]);

Повернення

$refund = $client->createRefund([
    'payment_id' => $payment->getId(),
    'amount' => ['value' => '500.00', 'currency' => 'RUB'],
    'description' => 'Частинковий повернення'
]);

Повернення може бути повним або частинковим. Кошти повертаються тим же способом, яким була проведена оплата.

Налаштування та часові терміни

• Реєстрація в ЮКаси, отримання shopId та secretKey — 1–3 робочих дні на стороні ЮКаси
• Розробка інтеграції (redirect-форма + webhook) — 1 робочий день
• Тестування в пісочниці + запуск у продакшні — ще 1 день