Интеграция платёжной системы ЮKassa на сайт

Интеграция платёжной системы ЮKassa на сайт

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

Варианты интеграции

Redirect (хостинговая форма) — покупатель перенаправляется на страницу ЮKassa. Минимум кода, максимум безопасности — данные карты вводятся на стороне платёжной системы. Подходит для большинства магазинов.

Embedded виджет — JavaScript-виджет встраивается на страницу оформления заказа. Покупатель не покидает сайт, но данные карты всё равно обрабатывает ЮKassa. Требует 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-обработка

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

• Проверять IP-адрес отправителя (список IP ЮKassa публикует в документации)
• Верифицировать подпись запроса
• Отвечать 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' => 'Частичный возврат'
]);

Возврат может быть полным или частичным. Средства возвращаются тем же способом, которым была проведена оплата.

Настройки и сроки

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