Подключение ЮKassa (Яндекс Касса) к сайту: пошаговое руководство

ЮKassa (бывшая Яндекс.Касса) — один из самых популярных платёжных шлюзов в России. Поддерживает оплату банковскими картами, СБП, ЮMoney, QIWI, наличными через терминалы и рассрочку. В этом руководстве разберём подключение через официальный PHP SDK.

Требования

• PHP 7.4+
• Composer для установки SDK
• Аккаунт в ЮKassa и настроенный магазин (yookassa.ru)
• shopId и секретный ключ из личного кабинета ЮKassa

1. Установка SDK

composer require yookassa/yookassa-sdk-php

2. Инициализация клиента

setAuth("ВАШ_SHOP_ID", "ВАШ_СЕКРЕТНЫЙ_КЛЮЧ");

3. Создание платежа

createPayment([
        "amount" => [
            "value"    => "1500.00",
            "currency" => "RUB",
        ],
        "confirmation" => [
            "type"       => "redirect",
            "return_url" => "https://your-site.ru/payment/success",
        ],
        "capture"     => true,
        "description" => "Заказ №12345",
        "metadata"    => [
            "order_id" => 12345,
        ],
    ], $idempotenceKey);

    // Получаем URL для редиректа пользователя
    $confirmationUrl = $payment->getConfirmation()->getConfirmationUrl();
    header("Location: " . $confirmationUrl);
    exit();

} catch (\Exception $e) {
    // Логируем ошибку
    error_log("YooKassa error: " . $e->getMessage());
    die("Ошибка создания платежа. Попробуйте позже.");
}

4. Обработка уведомления (webhook)

После оплаты ЮKassa отправляет POST-запрос на ваш обработчик. Укажите его URL в личном кабинете: Настройки → HTTP-уведомления.

setAuth("ВАШ_SHOP_ID", "ВАШ_СЕКРЕТНЫЙ_КЛЮЧ");

$source  = file_get_contents("php://input");
$data    = json_decode($source, true);

if (empty($data["object"]["id"])) {
    http_response_code(400);
    exit();
}

// Проверяем статус платежа через API (не доверяем входящим данным напрямую)
$paymentId = $data["object"]["id"];
$payment   = $client->getPaymentInfo($paymentId);

if ($payment->getStatus() === "succeeded") {
    $orderId = $payment->getMetadata()->offsetGet("order_id");
    // Помечаем заказ как оплаченный в вашей БД
    markOrderPaid((int) $orderId, $paymentId);
}

http_response_code(200);

5. Проверка статуса платежа вручную

getPaymentInfo("PAYMENT_ID");

echo "Статус: "  . $payment->getStatus()  . "\n"; // pending / waiting_for_capture / succeeded / canceled
echo "Сумма: "   . $payment->getAmount()->getValue() . " " . $payment->getAmount()->getCurrency() . "\n";
echo "Описание: " . $payment->getDescription() . "\n";

6. Возврат средств

createRefund([
    "payment_id" => "PAYMENT_ID",
    "amount"     => [
        "value"    => "500.00",
        "currency" => "RUB",
    ],
    "description" => "Частичный возврат по заказу №12345",
], uniqid("", true));

echo "Возврат создан: " . $refund->getId();

Типичные ошибки

Ошибка	Причина	Решение
401 Unauthorized	Неверный shopId или ключ	Проверить в ЛК ЮKassa
400 invalid_request	Неверный формат суммы	Сумма должна быть строкой с двумя знаками после точки: “100.00”
Webhook не приходит	Неверный URL или сервер не отвечает 200	Проверить доступность URL, убедиться что скрипт возвращает HTTP 200

Итог

ЮKassa подключается за несколько часов: установить SDK, создать платёж, настроить webhook-обработчик. Обязательно проверяйте статус платежа через API, а не доверяйте входящим уведомлениям без верификации.

Официальная документация: yookassa.ru/developers/payments/quick-start