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

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

Robokassa — агрегатор платежей, работающий на российском рынке с 2003 года. Поддерживает банковские карты, СБП, электронные кошельки (QIWI, ЮMoney), терминалы и рассрочку. Часто выбирают за низкий порог входа и простое подключение без длительного согласования.

Схема работы

Robokassa работает по классической redirect-схеме: сайт формирует ссылку с подписью и отправляет пользователя на страницу оплаты Robokassa. После оплаты Robokassa уведомляет сервер (ResultURL) и перенаправляет покупателя (SuccessURL/FailURL).

Параметры для подключения: MrchLogin (логин магазина), Password1 (для формирования подписи в запросах), Password2 (для проверки уведомлений от Robokassa).

Формирование ссылки оплаты

function buildRobokassaUrl(int $orderId, float $amount, string $description): string
{
    $login    = env('ROBOKASSA_LOGIN');
    $pass1    = env('ROBOKASSA_PASS1');
    $isTest   = env('ROBOKASSA_TEST', false) ? 1 : 0;

    // Подпись: MD5(Login:OutSum:InvId:Password1)
    $signature = md5("{$login}:{$amount}:{$orderId}:{$pass1}");

    $params = http_build_query([
        'MrchLogin'   => $login,
        'OutSum'      => number_format($amount, 2, '.', ''),
        'InvId'       => $orderId,
        'Desc'        => $description,
        'SignatureValue' => $signature,
        'IsTest'      => $isTest,
        'Culture'     => 'ru',
        'Encoding'    => 'utf-8',
        'Email'       => '', // email покупателя, если известен
    ]);

    return 'https://auth.robokassa.ru/Merchant/Index.aspx?' . $params;
}

Если используется фискализация, подпись включает ещё Receipt: MD5(Login:OutSum:InvId:Receipt:Password1) — порядок важен.

Обработка ResultURL

ResultURL — серверный коллбэк, не доступный пользователю. Именно здесь происходит смена статуса заказа:

public function result(Request $request): Response
{
    $outSum   = $request->input('OutSum');
    $invId    = $request->input('InvId');
    $received = strtolower($request->input('SignatureValue'));

    // Проверяем подпись с Password2
    $expected = strtolower(md5("{$outSum}:{$invId}:" . env('ROBOKASSA_PASS2')));

    if (!hash_equals($expected, $received)) {
        return response('bad sign', 400);
    }

    $order = Order::findOrFail($invId);

    // Дополнительно проверяем сумму
    if (abs((float)$outSum - $order->total) > 0.01) {
        return response('amount mismatch', 400);
    }

    $order->update(['status' => 'paid']);

    // Robokassa ожидает ответ строго в формате "OK{InvId}"
    return response("OK{$invId}");
}

Если Robokassa не получает OK{InvId}, уведомление повторяется несколько раз. Это одна из причин, почему обработчик должен быть идемпотентным.

SuccessURL и FailURL

На SuccessURL пользователь попадает после успешной оплаты. Здесь нельзя менять статус заказа — только отображать результат. Статус уже установлен через ResultURL. Можно дополнительно проверить:

public function success(Request $request): View
{
    $invId    = $request->input('InvId');
    $outSum   = $request->input('OutSum');
    $received = strtolower($request->input('SignatureValue'));
    $expected = strtolower(md5("{$outSum}:{$invId}:" . env('ROBOKASSA_PASS1')));

    // На SuccessURL подпись считается с Password1, не Password2
    if (!hash_equals($expected, $received)) {
        abort(403);
    }

    $order = Order::findOrFail($invId);
    return view('payment.success', compact('order'));
}

Фискализация

Чековые данные передаются в параметре Receipt (JSON, затем URL-encode):

$receipt = json_encode([
    'sno'   => 'usn_income',
    'items' => [
        [
            'name'     => 'Товар 1',
            'quantity' => 1,
            'sum'      => 1500.00,
            'tax'      => 'none',
            'payment_method' => 'full_payment',
            'payment_object' => 'commodity',
        ],
    ],
]);

// В подпись при наличии Receipt:
// MD5(Login:OutSum:InvId:urlencode(Receipt):Password1)
$signature = md5("{$login}:{$amount}:{$orderId}:" . urlencode($receipt) . ":{$pass1}");

Тестовый режим

В тестовом режиме (IsTest=1) оплата проходит без реального списания. Карты для тестирования указаны в документации Robokassa. Переключение на боевой режим — убрать IsTest и заменить ключи.

Активация нового магазина занимает до 2 рабочих дней. Для маркетплейсов и агрегаторов требуется отдельный договор.