![Схема Robokassa API — поток платежа от клиента к магазину и обратно]
Robokassa API — это набор протоколов и правил обмена данными между вашим сайтом/приложением и платежным шлюзом RoboKassa. С его помощью вы создаете оплаты, получаете статусы, принимаете уведомления (webhook Robokassa), оформляете возвраты и фискальные чеки.
Когда используется:
Для работы вам понадобится Личный кабинет продавца (см. также вход Robokassa) на официальном сайте провайдера (ООО Robokassa). В ЛК доступны настройки паролей/ключей, адресов Success/Fail/Result URL, параметров фискализации и интерфейс для ручных операций.
В основе Robokassa API — три ключевые сущности:
Обычно поток выглядит так:
Типовой набор взаимодействий с robokassa api:
Инициация платежа (redirect):
Получение статуса:
Возврат и отмена:
Фискализация:
Пример ключевых параметров при инициации:
| Параметр | Назначение |
|---|---|
| MerchantLogin | Логин магазина в Robokassa |
| OutSum | Сумма оплаты (десятичная строка) |
| InvId | ID заказа в вашей системе (уникальный номер) |
| Description | Описание заказа (для клиента) |
| Email/Phone | Контакты покупателя |
| Culture | Локаль интерфейса платежной формы |
| Shp_* | Пользовательские поля, возвращаются в webhook |
| SignatureValue | Контрольная подпись Robokassa |
Подпись Robokassa — главный механизм защиты целостности данных. Ее задача — гарантировать, что параметры не были изменены на пути от вашего сервера до шлюза и обратно.
Ключевые факты:
Упрощенная схема (пример, не подменяет официальную документацию):
Рекомендации по безопасности:
Мини‑пример на Python (SHA‑256):
import hashlib
def sign_initiate(merchant_login, out_sum, inv_id, password1, shp_params=None):
parts = [merchant_login, f"{out_sum}", str(inv_id), password1]
if shp_params:
# Включайте shp_* в порядке ключей по алфавиту, если это требуется в настройках вашей схемы подписи
for k in sorted(shp_params):
parts.append(f"{k}={shp_params[k]}")
raw = ":".join(parts)
return hashlib.sha256(raw.encode('utf-8')).hexdigest()
Webhook Robokassa — это серверный запрос на ваш Result URL, который сообщает о статусе оплаты. Его необходимо валидировать по подписи и параметрам.
Что приходит в webhook (набор параметров может отличаться):
| Поле | Описание |
|---|---|
| OutSum | Итоговая сумма платежа |
| InvId | Ваш ID заказа |
| SignatureValue | Подпись robokassa для проверки |
| Shp_* | Пользовательские параметры, если передавались |
| Доп. поля | Могут включать метод оплаты, валюту и др. |
Практика обработки:
Повторы: webhook может прийти несколько раз (сетевые задержки, ретраи). Поэтому ваш обработчик должен быть идемпотентным: повторная обработка одного и того же InvId не должна дублировать списания/проводки.
Безопасность:
Идемпотентность Robokassa — это стратегия, позволяющая безопасно обрабатывать повторные запросы и уведомления, не создавая дублей транзакций. Что стоит сделать:
Если API провайдера поддерживает RequestId/Idempotency-Key в заголовке — используйте. В противном случае достаточно грамотно работать с InvId и транзакциями.
Ниже — нейтральные примеры, иллюстрирующие общий принцип. Базовые URL уточняйте в вашем ЛК.
Формирование ссылки на оплату (redirect):
# ВАЖНО: используйте URL платежной формы из вашей документации в ЛК
PAY_URL="https://auth.robokassa.ru/Merchant/Index.aspx"
# Пример cURL (GET-параметры)
curl -G "$PAY_URL" \
--data-urlencode "MerchantLogin=demo-shop" \
--data-urlencode "OutSum=1990.00" \
--data-urlencode "InvId=12345" \
--data-urlencode "Description=Оплата заказа №12345" \
--data-urlencode "Email=user@example.com" \
--data-urlencode "shp_user=42" \
--data-urlencode "SignatureValue=3f5a...d1"
Проверка подписи в webhook на PHP (пример):
<?php
function verifyWebhook($outSum, $invId, $signatureValue, $password2, $shpParams = []) {
ksort($shpParams); // если ваша схема подписи требует сортировки shp_*
$parts = [$outSum, $invId, $password2];
foreach ($shpParams as $k => $v) {
$parts[] = "$k=$v";
}
$raw = implode(":", $parts);
$calc = strtolower(hash('sha256', $raw));
return strtolower($signatureValue) === $calc;
}
?>
Мини‑сервер на Node.js (Express) для приема webhook:
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.urlencoded({ extended: true }));
app.post('/result', (req, res) => {
const { OutSum, InvId, SignatureValue, ...rest } = req.body;
const shp = Object.fromEntries(Object.entries(rest).filter(([k]) => k.startsWith('shp_')));
const password2 = process.env.RB_PWD2;
const parts = [OutSum, InvId, password2];
Object.keys(shp).sort().forEach(k => parts.push(`${k}=${shp[k]}`));
const raw = parts.join(':');
const calc = crypto.createHash('sha256').update(raw).digest('hex');
if (calc !== String(SignatureValue).toLowerCase()) {
return res.status(400).send('bad sign');
}
// идемпотентная обработка InvId ...
// conduct order here
return res.status(200).send('OK');
});
app.listen(3000);
Для вопросов — загляните в FAQ или свяжитесь через телефон службы поддержки.
Robokassa API позволяет быстро запустить прием онлайн‑платежей: от генерации безопасной ссылки до приема webhook и автоматической фискализации. Соблюдайте правила подписи Robokassa, делайте обработчики идемпотентными и не считайте секреты на клиенте — это обеспечит надежность и предсказуемость платежного потока.
Готовы принять первый платеж? Перейдите к подключению интернет‑эквайринга на странице Подключить и оформите интеграцию. Если остались вопросы, изучите FAQ или уточните детали на официальном сайте.