Интеграция Robokassa: API, CMS и вебхуки — дорожная карта

Получить CloudPayments бесплатно

Интеграция Robokassa: API, CMS и вебхуки — дорожная карта

Table of contents

План интеграции и требования

Интеграция Robokassa — это совокупность нескольких узлов: платежная форма (редирект), серверные уведомления (вебхуки), API для статусов/счетов и модули CMS. Перед стартом убедитесь, что у вас есть:

Архитектура и сценарии оплаты

Robokassa поддерживает классическую схему редиректа на платежную форму и серверные уведомления по результатам. Ключевые сценарии:

С точки зрения протокола, ядро состоит из:

Быстрый старт: выберите подход

Выбор интеграционного пути зависит от стека и сроков:

Основные точки интеграции и эндпоинты

Robokassa исторически использует aspx‑маршруты, поэтому вы встретите Index.aspx в URL. Ниже — обобщенная карта узлов.

Узел Метод Назначение Примечание
Платежная форма (Merchant/Index.aspx) GET/POST Редирект покупателя на оплату Параметры: MerchantLogin, OutSum, InvId, Description, SignatureValue, Culture, IsTest, Shp_*
SuccessURL GET Возврат после успешной оплаты Отображение результата покупателю
FailURL GET Возврат при прерывании/ошибке Возможность повторной оплаты
ResultURL (вебхук) POST Серверное уведомление о платеже Подпись по паролю №2, ответ OK{InvId}
API статуса GET/POST Запрос статуса платежа/инвойса Используйте для сверки, если вебхук не дошел

Примечание: конкретные пути API статусов зависят от подключения и могут отличаться; ориентируйтесь на актуальную документацию в ЛК и спецификации. Для продакшн‑редиректов чаще встречается домен https://auth.robokassa.ru/Merchant/Index.aspx.

Подписи и безопасность: SHA-256

Корректная проверка подписи — основа безопасности. Рекомендуется алгоритм SHA‑256 (MD5 — устаревающий вариант). В ЛК включите SHA‑256 и всегда:

Пример строки для подписи (упрощенно):

MerchantLogin:OutSum:InvId:Password#

С добавлением пользовательских полей Shp_* они включаются по правилам провайдера (обычно по алфавиту), иначе проверка подписи может не пройти.

Проверка подписи SHA‑256 в PHP:

<?php
$merchant = $_POST['MerchantLogin'] ?? '';
$outSum   = $_POST['OutSum'] ?? '';
$invId    = $_POST['InvId'] ?? '';
$sig      = strtolower($_POST['SignatureValue'] ?? '');
$password2 = getenv('ROBOKASSA_PASSWORD2');

// Включите Shp_* параметры в подпись, отсортировав по ключу
$shp = [];
foreach ($_POST as $k => $v) {
  if (stripos($k, 'Shp_') === 0) { $shp[$k] = $v; }
}
ksort($shp);
$shpStr = '';
foreach ($shp as $k => $v) { $shpStr .= ":$k=$v"; }

$base = "$outSum:$invId:$password2$shpStr"; // для ResultURL
$calc = strtolower(hash('sha256', $base));

if ($calc !== $sig) {
  http_response_code(400);
  exit('bad signature');
}
// Возвращаем OK с номером счета
echo 'OK' . (int)$invId;

Проверка подписи в Node.js:

const crypto = require('crypto');
function verifySignature({ outSum, invId, password2, shpParams, signature }) {
  const suffix = Object.keys(shpParams || {})
    .sort()
    .map(k => `:${k}=${shpParams[k]}`)
    .join('');
  const base = `${outSum}:${invId}:${password2}${suffix}`;
  const calc = crypto.createHash('sha256').update(base).digest('hex').toLowerCase();
  return calc === String(signature).toLowerCase();
}

Дополнительно:

CMS: 1C‑Bitrix и WooCommerce

Если вы используете готовые CMS, интеграция ускоряется в разы.

Совет: используйте «песочницу» и журнал запросов в CMS для отслеживания проблем. В случае ошибок авторизации смотрите раздел troubleshooting по merchant/auth.

Серверная интеграция: PHP, Node.js и ASP.NET

Ниже — минимальные примеры. Это не полноценный SDK, а «скелет» для быстрой интеграции.

<?php
$merchantLogin = getenv('ROBOKASSA_LOGIN');
$password1 = getenv('ROBOKASSA_PASSWORD1');
$invoiceId = 12345; $amount = '1490.00';
$desc = 'Оплата заказа #12345';
$base = "$merchantLogin:$amount:$invoiceId:$password1";
$sig = hash('sha256', $base);
$query = http_build_query([
  'MerchantLogin' => $merchantLogin,
  'OutSum' => $amount,
  'InvId' => $invoiceId,
  'Description' => $desc,
  'SignatureValue' => $sig,
  'IsTest' => 1,
]);
$url = 'https://auth.robokassa.ru/Merchant/Index.aspx?' . $query;
header("Location: $url");

class Robokassa {
  constructor({ login, pass1, pass2, baseUrl = 'https://auth.robokassa.ru' }) {
    this.login = login; this.pass1 = pass1; this.pass2 = pass2; this.baseUrl = baseUrl;
  }
  createPaymentUrl({ invId, amount, description, isTest = 1, extra = {} }) {
    const crypto = require('crypto');
    const shpSuffix = Object.keys(extra).sort().map(k => `:${k}=${extra[k]}`).join('');
    const signature = crypto.createHash('sha256')
      .update(`${this.login}:${amount}:${invId}:${this.pass1}${shpSuffix}`)
      .digest('hex');
    const params = new URLSearchParams({ MerchantLogin: this.login, OutSum: amount, InvId: invId, Description: description, SignatureValue: signature, IsTest: String(isTest) });
    for (const [k,v] of Object.entries(extra)) params.append(k, v);
    return `${this.baseUrl}/Merchant/Index.aspx?${params.toString()}`;
  }
}

string login = Config.Login;
string pass1 = Config.Pass1;
string amount = "1490.00";
int invId = 12345;
string baseStr = $"{login}:{amount}:{invId}:{pass1}";
string sig = BitConverter.ToString(System.Security.Cryptography.SHA256.Create().ComputeHash(System.Text.Encoding.UTF8.GetBytes(baseStr))).Replace("-", "").ToLower();
string url = $"https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin={login}&OutSum={amount}&InvId={invId}&Description=Order%20{invId}&SignatureValue={sig}&IsTest=1";
Response.Redirect(url);

Вебхуки Robokassa: ResultURL и обработка

Вебхуки Robokassa — это, по сути, серверные уведомления на ваш ResultURL. Правила обработки:

Полезные поля в ResultURL (могут отличаться в зависимости от конфигурации):

Поле Описание
OutSum Сумма платежа
InvId Идентификатор счета/заказа
SignatureValue Подпись SHA‑256/MD5
Shp_* Пользовательские параметры мерчанта

Если вебхук не дошел, запросите статус платежа через API статусов или воспользуйтесь отчетами в ЛК — см. отчеты и аналитика.

Тестирование и отладка

Расширенные сценарии

Чек-лист внедрения

Заключение

Интеграция Robokassa строится вокруг трех опор: корректная подпись (SHA‑256), стабильный ResultURL (вебхук) и четкая логика статусов. Выберите подход — модуль для CMS или прямую работу с Robokassa API — и двигайтесь шаг за шагом по дорожной карте выше. Готовы ускорить запуск и повысить конверсию? Изучите смежные разделы (форма оплаты, Sandbox, методы оплаты) и приступайте к настройке уже сегодня.

Присоединяйтесь и принимайте платежи с первого дня — начните с личного кабинета и перейдите к настройке платежной формы.

Получить CloudPayments бесплатно