Робокасса: Result URL, проверка подписи и ошибка 29
Ошибка 29 в Робокассе — неверная подпись SignatureValue. Какой пароль где, тестовый режим, Shp_ и Receipt, ответ OK{InvId} и проверенный код на Python и PHP.
Опубликовано Обновлено 17 минут чтения
- робокасса
- result url
- signaturevalue
- ошибка 29
- платежи
Ошибка 29 в Робокассе означает неверный параметр SignatureValue: подпись запроса на оплату не совпала с той, что посчитала Робокасса. Сначала проверьте пароль. Запрос на оплату подписывается паролем #1, а при IsTest=1 — тестовым паролем #1 из технических настроек магазина. Потом сверьте идентификатор магазина, алгоритм хеша, параметры Shp_, чек Receipt и строку суммы. Уведомление на Result URL подписано другим паролем, #2, и в ответ на него Робокасса ждёт текст OK{InvId}.
Формулы ниже взяты из документации Робокассы: интерфейс оплаты, уведомления и переадресация, тестовый режим. Пароли в примерах выдуманы: primer-parol-1 и primer-parol-2.
Три подписи и два пароля
Подписей у Робокассы три, паролей два, и перепутать их легко:
| Что подписывается | Строка | Пароль |
|---|---|---|
| Запрос на оплату | MerchantLogin:OutSum:InvId[:модификаторы]:Пароль#1[:Shp_…] | #1 |
| Уведомление на Result URL | OutSum:InvId:Пароль#2[:Shp_…] | #2 |
| Переход на Success URL | OutSum:InvId:Пароль#1[:Shp_…] | #1 |
Части строки соединяются двоеточием без пробелов. В тестовом режиме строки те же, но пароли берутся из тестового блока технических настроек магазина.
Оплату подтверждает только уведомление на Result URL. Success URL документация описывает как страницу для покупателя, а статус заказа Робокасса сама не меняет: это делает ваш обработчик. В каком порядке приходят уведомление и переход покупателя, документация не говорит. Поэтому страница Success URL не должна рассчитывать, что заказ уже отмечен оплаченным: покажите «платёж обрабатывается», если уведомления ещё не было.
Ошибка 29 в Робокассе: что проверить
Пример подписи запроса на оплату: логин demo, сумма 100.00, счёт 450009, два пользовательских параметра.
demo:100.00:450009:primer-parol-1:Shp_login=Vasya:Shp_oplata=1 MD5: a5833f7a3ad0d0fbb43935d826865505
Что сверить, по порядку:
- Пароль и режим. С
IsTest=1нужна тестовая пара паролей. Документация прямо пишет, что боевые пароли в тестовом окружении дают ошибку 29. БезIsTest, сIsTest=0или с пустым значением создаётся боевой платёж. - Идентификатор магазина.
MerchantLoginв подписи и в запросе один и тот же, из технических настроек. - Алгоритм хеша. Код считает тем же методом, что выбран в настройках магазина. По умолчанию это MD5.
Shp_-параметры. Идут после пароля, отсортированы по имени, записаны какShp_имя=значение. Регистр имени важен:Shp_itemв запросе иshp_itemв подписи по документации дают ошибку. В имени послеShp_допустимы латинские буквы, цифры и подчёркивание.- Сумма.
OutSum— число через точку, например123.45. В подписи должна стоять ровно та строка, что уходит в форму:100и100.00дают разные хеши. Отформатируйте сумму один раз и подставляйте одну и ту же переменную в оба места. - Пустой
InvId. Если номер счёта не передаётся, место под него остаётся пустым:demo:100.00::primer-parol-1. - Модификаторы.
Receipt,StepByStep,ResultUrl2,SuccessUrl2,SuccessUrl2Method,FailUrl2,FailUrl2Method,Tokenставятся междуInvIdи паролем — только переданные и строго в этом порядке. Пример из документации:MerchantLogin:OutSum:InvId:Receipt, затем пароль #1, затемShp_order=25— всё через двоеточие. - Чек
Receipt. Перед подписью JSON чека кодируется для URL, и в подпись идёт уже закодированная строка:%7B%22items%22…. В примерах документации эта же строка стоит в значении поля формы, а в адресе запроса она оказывается закодированной второй раз:%257B…. Если ошибка 29 появляется только у заказов с чеком, выведите строку подписи в лог и посмотрите, с чего начинаетсяReceipt: с{— не закодирован, с%257B— закодирован дважды.
Соседние коды ошибок
Из раздела «Типовые ошибки интерфейса оплаты»:
| Код | Что значит по документации |
|---|---|
| 25 | магазин не активирован: боевой режим без активации или неверный идентификатор магазина |
| 26 | магазин не найден: опечатка в идентификаторе |
| 29 | неверный SignatureValue |
| 30 | неверный параметр счёта |
| 31 | неверная сумма: при переходе на оплату сумма должна быть передана и быть больше нуля |
| 40 | повторная оплата счёта с тем же номером; в тестовом режиме номера не учитываются и этой ошибки не дают |
| 41 | ошибка на старте операции: повторить, при повторе — в поддержку |
Коды 20, 21, 22, 23, 24, 27, 28, 32, 36, 37, 43 и 500 документация называет внутренними ошибками сервиса. С ними пишут в поддержку Робокассы.
Из кода 40 следует ловушка тестового режима: при IsTest=1 один и тот же InvId проходит сколько угодно раз, а в боевом режиме второй платёж с этим номером получит ошибку 40.
Оплата прошла, а заказ не оплачен
Если ошибки на странице оплаты нет, а заказ так и висит неоплаченным, дело в Result URL. Найдите свой симптом:
| Симптом | Причина и как проверить | Что сделать |
|---|---|---|
| В логах веб-сервера нет запроса от Робокассы | Result URL недоступен из интернета, в адресе опечатка, запросы режет фильтр по IP. Временно поставьте в Result URL адрес приёма hook.csap.ru и проведите тестовую оплату: так видно, уходит ли уведомление вообще | Исправить адрес, открыть доступ, добавить IP Робокассы в белый список |
Запрос есть, ответ 403 или ошибка CSRF | Фреймворк требует CSRF-токен в POST. Django без токена отвечает 403, Laravel тоже отклоняет такой запрос | Исключить маршрут Result URL из CSRF-проверки: в Django — csrf_exempt, в Laravel — список исключений CSRF-middleware |
| Запрос есть, ваш код отвечает «подпись неверна» | Проверка идёт паролем #1 вместо #2, тестовым паролем вместо боевого или наоборот, сумма переформатирована, алгоритм не тот. Посчитайте хеш вручную от полей из лога | Проверять паролем #2 того режима, в котором идёт оплата; сумму брать строкой как есть |
Подпись сходится, но в ответе не OK{InvId} | Ответ отдаёт шаблон страницы, редирект, просто OK или лишние байты. Проверьте curl -i и od -c | Отдавать ровно OK и номер счёта, текстом |
| Тестовые оплаты подтверждаются, боевые — нет | Пароль #2 задан тестовый, а платёж боевой: признака теста в уведомлении нет | Пароль #2 брать из настройки окружения |
Отдельно про лишние байты. PHP-файл, сохранённый в UTF-8 с BOM, отдаёт эти три байта до <?php. Ответ получается \xEF\xBB\xBFOK450009: на экране не видно, а od -c покажет 357 273 277 перед O. Как Робокасса относится к таким ответам, документация не пишет, проще не проверять это на боевом магазине.
Result URL: что приходит и что ответить
После успешной оплаты Робокасса отправляет запрос на Result URL. Адрес задаётся в технических настройках магазина, данные всегда в UTF-8. Метод отправки выбирается в настройках, поэтому обработчик ниже принимает и GET, и POST.
| Параметр | Что это |
|---|---|
OutSum | сумма платежа |
InvId | номер счёта в магазине |
Fee | комиссия Робокассы |
EMail | почта, которую указал покупатель |
SignatureValue | хеш, шестнадцатеричное число (0–9, A–F) |
PaymentMethod | способ оплаты |
IncCurrLabel | валюта, которой платил клиент |
Shp_* | ваши параметры, если они были в запросе на оплату |
Пример из документации с выдуманным паролем:
OutSum=100.000000 InvId=450009 Shp_login=Vasya Shp_oplata=1 100.000000:450009:primer-parol-2:Shp_login=Vasya:Shp_oplata=1 MD5: 171EE21951048F40F246C771AFA48B94
Если подписи совпали, ответьте текстом OK и номером счёта: OK450009. Если не совпали, уведомление считается некорректным.
Семь деталей, на которых теряют время:
- Сумма — строкой. В тестовом режиме
OutSumможет прийти с двумя знаками после точки, в боевом — с шестью. Хеш считается от той строки, что пришла:100.00вместо100.000000даёт другую подпись. Сравнивать с суммой заказа — уже после проверки подписи и как десятичное число, а неfloat. - Сравнение подписи —
hmac.compare_digestиhash_equals, а не==. Обычное сравнение останавливается на первом несовпадающем символе, и по скорости ответа подпись можно подбирать по одному символу; у этих функций время сравнения не зависит от того, где строки разошлись. - Регистр хеша. Робокасса присылает хеш заглавными буквами, а
hexdigest()в Python иhash()в PHP дают строчные. Приведите обе стороны к одному регистру. - Признака теста нет. В списке параметров Result URL нет
IsTest. Обработчик не узнает из уведомления, каким паролем проверять. Пароль #2 задавайте настройкой окружения: на тестовом стенде тестовый, на боевом рабочий. - Повторы. Повторяет ли Робокасса уведомление, если ответ не
OK{InvId}, документация не говорит. Обработчик всё равно делайте идемпотентным: второе такое же уведомление должно снова получитьOK{InvId}и не выдать товар второй раз. - IP. Если вы фильтруете входящие запросы, Робокасса просит добавить в белый список
185.59.216.65и185.59.217.65. - Лимиты адреса при отладке. На бесплатном тарифе hook.csap.ru сверх 5 запросов в секунду и 500 в месяц адрес отвечает
429. Повторит ли Робокасса такое уведомление, документация не говорит, поэтому для отладки хватит нескольких тестовых платежей.
Передавайте свой InvId. Если он пустой, равен 0 или не передан, Робокасса присвоит номер сама, и сопоставлять уведомление с заказом придётся по Shp_-параметрам. Номер в ответе OK{InvId} всегда берите из уведомления.
Если уведомление так и не пришло, состояние платежа можно запросить через XML-интерфейс OpStateExt с подписью MerchantLogin:InvoiceID:Пароль#2. Код состояния 100 — платёж проведён. Для тестовых платежей метод не работает.
Обработчик Result URL на Python и PHP
Оба обработчика делают одно и то же:
- Берут параметры из формы (POST) или из строки запроса (GET).
- Собирают
Shp_по имени и считают хеш паролем #2. Несовпадение —400иbad sign. - В одной транзакции находят заказ и сверяют сумму. Заказа нет или сумма другая —
400иbad order, запись в лог для разбора вручную. - Отмечают заказ оплаченным с условием
paid_at IS NULL. Повтор того же уведомления ничего не меняет и снова получаетOK{InvId}.
Какой HTTP-код отдавать при ошибке, документация не говорит. Главное — не отвечать OK{InvId}. В лог пишется номер счёта и причина, без пароля и строки подписи.
Заказы для примера лежат в SQLite, в рабочем коде это ваша база:
CREATE TABLE orders (inv_id TEXT PRIMARY KEY, amount TEXT NOT NULL, paid_at TEXT);
INSERT INTO orders (inv_id, amount) VALUES ('450009', '100.00');Python (Flask)
import hashlib import hmac import logging import os import sqlite3 from decimal import Decimal from flask import Flask, request app = Flask(__name__) log = logging.getLogger("robokassa") # Пароль #2 из технических настроек магазина. Для тестовых платежей — # тестовый пароль #2: в уведомлении нет признака теста, режим задаёт настройка. PASSWORD2 = os.environ["ROBOKASSA_PASSWORD2"] # Алгоритм — тот, что выбран в технических настройках (по умолчанию MD5). HASH_ALG = os.environ.get("ROBOKASSA_HASH", "md5") DB_PATH = os.environ.get("SHOP_DB", "shop.db") def signature_ok(p): # Сумма идёт в хеш строкой, как пришла: 100.000000 и 100.00 дают разные хеши. base = [p.get("OutSum", ""), p.get("InvId", ""), PASSWORD2] base += [f"{k}={v}" for k, v in sorted(p.items()) if k.startswith("Shp_")] mine = hashlib.new(HASH_ALG, ":".join(base).encode("utf-8")).hexdigest() got = p.get("SignatureValue", "").lower() # Робокасса шлёт A–F # Байты, а не str: на не-ASCII в подписи compare_digest(str, str) падает. return hmac.compare_digest(mine.encode(), got.encode()) def mark_paid(inv_id, out_sum): """False — заказа нет или сумма другая. Повтор уведомления снова даёт True.""" db = sqlite3.connect(DB_PATH) try: with db: # одна транзакция: проверка и отметка row = db.execute( "SELECT amount FROM orders WHERE inv_id = ?", (inv_id,) ).fetchone() # Decimal, а не float: 100.000000 == 100.00 и никаких 0.1 + 0.2. if row is None or Decimal(row[0]) != Decimal(out_sum): return False # Условие paid_at IS NULL делает повтор безвредным. db.execute( "UPDATE orders SET paid_at = CURRENT_TIMESTAMP" " WHERE inv_id = ? AND paid_at IS NULL", (inv_id,), ) return True finally: db.close() @app.route("/robokassa/result", methods=["GET", "POST"]) def robokassa_result(): p = request.values # POST — поля формы, GET — параметры строки inv_id = p.get("InvId", "") if not signature_ok(p): log.warning("robokassa: bad signature, InvId=%s", inv_id) return "bad sign", 400 if not mark_paid(inv_id, p["OutSum"]): log.error("robokassa: order mismatch, InvId=%s OutSum=%s", inv_id, p["OutSum"]) return "bad order", 400 return f"OK{inv_id}", 200, {"Content-Type": "text/plain; charset=utf-8"} if __name__ == "__main__": app.run(port=8000)
Запуск: ROBOKASSA_PASSWORD2=primer-parol-2 python app.py.
PHP
<?php // Пароль #2 из технических настроек магазина. Для тестовых платежей — // тестовый пароль #2: в уведомлении нет признака теста, режим задаёт настройка. $password2 = getenv('ROBOKASSA_PASSWORD2'); // Алгоритм — тот, что выбран в технических настройках (по умолчанию MD5). $alg = getenv('ROBOKASSA_HASH') ?: 'md5'; $p = $_SERVER['REQUEST_METHOD'] === 'POST' ? $_POST : $_GET; $outSum = $p['OutSum'] ?? ''; // строкой, как пришла: 100.000000 $invId = $p['InvId'] ?? ''; $shp = []; foreach ($p as $name => $value) { if (strpos($name, 'Shp_') === 0) { $shp[$name] = "$name=$value"; } } ksort($shp, SORT_STRING); $base = implode(':', array_merge([$outSum, $invId, $password2], array_values($shp))); $mine = hash($alg, $base); $sig = $p['SignatureValue'] ?? ''; $got = is_string($sig) ? strtolower($sig) : ''; // Робокасса шлёт A–F; массив — не подпись header('Content-Type: text/plain; charset=utf-8'); if (!hash_equals($mine, $got)) { error_log("robokassa: bad signature, InvId=$invId"); http_response_code(400); exit('bad sign'); } $db = new PDO('sqlite:' . (getenv('SHOP_DB') ?: 'shop.db')); $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); $db->beginTransaction(); // одна транзакция: проверка и отметка $st = $db->prepare('SELECT amount FROM orders WHERE inv_id = ?'); $st->execute([$invId]); $amount = $st->fetchColumn(); // bccomp сравнивает строки как десятичные числа: 100.000000 == 100.00, без float. if ($amount === false || bccomp($amount, $outSum, 6) !== 0) { $db->rollBack(); error_log("robokassa: order mismatch, InvId=$invId OutSum=$outSum"); http_response_code(400); exit('bad order'); } // Условие paid_at IS NULL делает повтор безвредным. $db->prepare('UPDATE orders SET paid_at = CURRENT_TIMESTAMP WHERE inv_id = ? AND paid_at IS NULL') ->execute([$invId]); $db->commit(); echo "OK$invId";
Запуск: ROBOKASSA_PASSWORD2=primer-parol-2 php -S 127.0.0.1:8000 result.php. Нужны расширения pdo_sqlite и bcmath.
Если в магазине выбран не MD5, задайте ROBOKASSA_HASH, например sha256. Этот вариант тоже прогнан на обоих обработчиках.
Проверка одним запросом
curl -X POST http://localhost:8000/robokassa/result \ -d 'OutSum=100.000000&InvId=450009&Shp_login=Vasya&Shp_oplata=1' \ -d 'SignatureValue=171EE21951048F40F246C771AFA48B94' # OK450009
Оба обработчика прогнаны на одном наборе запросов, ответы совпали:
| Запрос | Ответ | Заказ |
|---|---|---|
| POST, подпись паролем #2 | 200 OK450009 | отмечен оплаченным |
| то же уведомление повторно | 200 OK450009 | время оплаты не изменилось |
| POST, поля в другом порядке | 200 OK450009 | — |
| GET, подпись паролем #2 | 200 OK450009 | — |
| POST, подпись строчными буквами | 200 OK450009 | — |
OutSum=100.00 и подпись от 100.00, как в тестовом режиме | 200 OK450009 | — |
| POST, подпись паролем #1 | 400 bad sign | — |
OutSum=100.00, подпись от 100.000000 | 400 bad sign | — |
POST без SignatureValue | 400 bad sign | — |
| подпись верна, сумма 50 при заказе на 100 | 400 bad order | не изменён |
| подпись верна, заказа 777 нет | 400 bad order | — |
Посмотреть уведомление на hook.csap.ru
Пока обработчика нет или он отвечает «подпись неверна», полезно увидеть, что Робокасса присылает на самом деле, и проверить пароль #2 отдельно от своего кода.
- Откройте hook.csap.ru и скопируйте адрес приёма. Допишите к нему путь, например
/robokassa/result, и вставьте в поле Result URL в технических настройках магазина. - На странице адреса нажмите «Правила». В блоке «Проверка подписи» выберите провайдер «Робокасса» и тот же алгоритм хеша, что в магазине. В поле «Секрет» вставьте пароль #2, для тестовых платежей — тестовый пароль #2. Нажмите «Сохранить проверку».
- Проведите тестовую оплату. В карточке запроса появится строка «Подпись: верна» или «Подпись: не сошлась», а в раскрытии строки — по каким полям считали.
Ниже — уведомление из примера документации, подписанное паролем primer-parol-2 и отправленное на адрес сервиса. Это не платёж из кабинета Робокассы. Пометка «не с адреса провайдера» появилась потому, что запрос пришёл не с IP 185.59.216.65 или 185.59.217.65. Итог проверки решает подпись, адрес — дополнительный признак.
Проверку можно настроить и до первого платежа: «Прислать пример» → «Робокасса» → «Оплата на Result URL» отправит на адрес уведомление, подписанное паролем из блока «Проверка подписи». Пример приходит на корень адреса (/), а не на ваш путь.
Без правил адрес отвечает 200 с пустым телом, для Робокассы это не подтверждение. Если нужно, чтобы тестовые платежи подтверждались до появления кода, хватит двух правил. Первое: условие «Подпись провайдера» — «верна», действие «Шаблонный ответ» с кодом 200, Content-Type text/plain; charset=utf-8 и телом OK{{ form.InvId }}{{ request.query.InvId }} — первая подстановка срабатывает на POST, вторая на GET. Второе: то же условие с отметкой «НЕ», действие «Статический ответ» 400 с телом bad sign. На стенде верное уведомление получило 200 OK450009, подписанное паролем #1 — 400 bad sign. Заказ правило оплаченным не отметит, это работа обработчика.
Обработчик на localhost через туннель
Туннель передаёт уведомление с адреса приёма на ваш компьютер и возвращает отправителю ответ вашего кода. Нужен вход в аккаунт. CLI ставится так (вариант для Windows — на странице туннеля):
curl -fsSL https://hook.csap.ru/cli/install.sh | WEBHOOKS_BASE_URL=https://hook.csap.ru sh webhooks login --web --server https://hook.csap.ru webhooks tunnel --endpoint ВАШ_ТОКЕН --target http://localhost:8000
Вывод терминала на тестовом стенде сервиса: обработчик на Flask, два уведомления из примера выше, подписанные паролем #2 и паролем #1:
туннель открыт: UDmPGuYGoFnkN7wWqvp65e → http://localhost:8000 11:24:15 b3c22a43 POST /robokassa/result → 200 (4ms) 11:24:15 3c177a98 POST /robokassa/result → 400 (3ms)
Пока туннель подключён, правила адреса не работают: отвечает ваш код. Если локальный сервер не отвечает, отправитель получит 502. Упавший обработчик можно исправить и повторить сохранённое уведомление по номеру из ленты:
$ webhooks replay 49 --target http://localhost:8000 --show-body POST http://localhost:8000/robokassa/result → 200 OK за 3ms, 8 Б OK450009
Перед запуском
- Пароль #1 подписывает запрос на оплату и проверяет Success URL, пароль #2 проверяет Result URL. В тесте — тестовая пара.
- Сумма в подписи — та же строка, что в запросе или уведомлении.
Shp_после пароля, по алфавиту, в том же регистре;Receiptзакодирован для URL один раз.- Result URL доступен из интернета, не закрыт CSRF-проверкой и отвечает ровно
OK{InvId}. - Повтор уведомления не выдаёт товар второй раз.
- Прогнан хотя бы один тестовый и один боевой платёж — этого требует и чек-лист Робокассы.
Проверено 10.10.2026 по документации Робокассы и на сервисе hook.csap.ru.
Адрес для приёма уведомлений выдаётся без регистрации на hook.csap.ru, туннель — после входа, тарифы — на странице /pricing.