Skip to main content
Частые вопросы — короткие ответы. Нужна пошаговая диагностика по симптому (деревья «платёж застрял», «вебхук не приходит», таймауты) — на странице Что делать, если не работает. Полный список кодов ошибок — Справочник кодов ошибок.

​
Аутентификация и подпись

Почти всегда причина одна: подписали одну строку тела, а отправили другую. Библиотека могла переупорядочить поля JSON или добавить пробелы, и байты тела перестали совпадать с подписанными.Что проверить:
  1. Сериализуйте тело один раз в переменную и используйте её и для подписи, и для отправки.
  2. Каноническая строка — ровно timestamp\nPOST\npath\nbody, с переводами строк \n.
  3. path — с ведущим слэшем (/v1/payment), без базового URL.
  4. Подпись — hex в нижнем регистре.
→ Как подписать запрос
X-Timestamp отсутствует или не число. Передавайте unix‑секунды (целое), не миллисекунды.
Если часы разошлись больше чем на 5 минут — код будет merchant.bad_signature (проверка окна ±5 мин встроена в сверку подписи), а не auth.bad_timestamp. Синхронизируйте время (NTP).
У вас включён IP‑allowlist, а запрос идёт с адреса вне списка. Либо добавьте IP вашего backend, либо временно выключите контроль.
Это разные алгоритмы. Подпись запроса — timestamp\nMETHOD\npath\nbody. Подпись вебхука — timestamp.сырое_тело (точка‑разделитель, без метода и пути), другим секретом. → Объект вебхука

​
Платежи

Скорее всего это валюто‑агностичный счёт (is_multi: true): вы не задали to_currency/network, и адрес выделится только после того, как покупатель выберет валюту на hosted‑странице через /v1/pay/{id}/select. Если адрес нужен сразу — задайте валюту и сеть при создании. → Три режима создания счёта
У валюты несколько сетей (например, у USDT их много), а network вы не указали. Укажите сеть явно или используйте валюту с единственной сетью. → Поддерживаемые сети
Сумма ниже минимума сети. На дорогих сетях (Ethereum, Bitcoin) минимум есть. Увеличьте сумму или используйте дешёвую сеть (Tron, Polygon, BSC).
Проверьте промежуточные статусы: confirm_check означает, что транзакцию видят и ждут подтверждений сети. Число подтверждений зависит от суммы и сети — крупный платёж ждёт дольше. Пока не достигнут порог, статус не станет paid. → Приём первого платежа
Зависит от настроек. Если сумма в пределах допуска — счёт всё равно paid. Если нет и срок вышел — wrong_amount, и средства вернутся при включённом автовозврате. → Недоплата и переплата

​
Вебхуки

Пройдите по списку:
  1. Endpoint зарегистрирован? Вызовите /v1/webhooks и сохраните секрет. Без регистрации доставок нет вовсе — даже per‑объектный url_callback игнорируется (без секрета endpoint подписывать нечем, доставка не создаётся).
  2. URL публично доступен по HTTPS? Приватные/локальные адреса запрещены SSRF‑проверкой.
  3. Отправьте пробное событие и посмотрите status_code. → Отладка вебхуков
  4. Проверьте журнал доставок — статус pending/dead и last_error подскажут причину. → /v1/webhooks/deliveries
  • Берёте ли вы сырое тело (до JSON‑парсинга)? Пересериализация меняет байты.
  • Правильный ли алгоритм: hex(HMAC-SHA256(secret, "{timestamp}." + сырое_тело))?
  • Тот ли секрет — из /v1/webhooks, а не ключ API?
  • Пробные тела (is_test: true) не подписаны — их проверять подписью не нужно.
Это нормально: доставка at‑least‑once. Обязательно дедуплицируйте по uuid + status и обрабатывайте повтор как no‑op. → Настройка вебхуков
Вы вернули не‑2xx (или запрос упал по таймауту). Диспетчер считает это провалом и повторяет. Отвечайте 2xx только после успешной обработки; если обработка не удалась — тогда да, пусть повторит.

​
Выплаты и баланс

Возможны незрелые средства: депозит на балансе виден, но ещё не набрал подтверждений и невыводим. Выводимый остаток может быть меньше показанного в /v1/balance. Дождитесь подтверждений. Отдельный код для этого случая — 409 payout.funds_maturing.
Средства ещё дозревают (maturity‑холд для reorg‑безопасности). Это временно — повторите позже с backoff или выведите уже зрелую часть.
Вы указали адрес, принадлежащий самому шлюзу (self‑dealing запрещён). Укажите внешний адрес.
Для выплаты order_id обязателен — это ваш бизнес‑ключ дедупликации. Всегда задавайте уникальный. Он дополняет (а не заменяет) HTTP‑заголовок Idempotency-Key. → Устойчивый клиент
Это ожидаемо: элементы независимы. Разбирайте результат поэлементно — у неуспешных виден признак неудачи и причина. В батче это items[].status + items[].error, в легаси /v1/payout/mass — success: false + message. → Массовые операции
Используйте батч POST /v1/payout/batch: до 5000 выплат одним подписанным запросом, обработка асинхронная, результат — через /v1/batch/info. Цикл из отдельных вызовов гарантированно упрётся в лимит частоты. → Массовые операции

​
Общее

Это временные ошибки. Повторяйте с экспоненциальным backoff. Благодаря идемпотентности повтор денег‑движущих операций безопасен (дубля не будет) — при условии, что вы повторяете тот же запрос: с тем же HTTP‑заголовком Idempotency-Key и тем же order_id. → Идемпотентность
Это HTTP‑заголовок с любым уникальным значением (до 255 символов), который вы генерируете до первой отправки и не меняете при ретраях. Повтор с тем же ключом вернёт тот же ответ и заголовок Idempotent-Replayed: true вместо создания дубля.Формально не обязателен, но настоятельно рекомендуется. Второй, независимый механизм защиты — ваш order_id (для выплат он обязателен). Опасен только случай, когда нет ни того, ни другого: тогда повтор создаст дубль. → Устойчивый клиент
Нет. Не все 409 финальны:
  • payout.funds_maturing — средства дозревают, повторите позже, выплата пройдёт;
  • idempotency.in_progress — ваш прежний запрос ещё выполняется, подождите и повторите;
  • payout.frozen — временная защита, повторите позже;
  • payout.insufficient_funds — вот это по‑настоящему «денег нет», повтор не поможет.
→ Устойчивый клиент
Превышена частота запросов. Снизьте темп и повторяйте с backoff. → Ограничение частоты
Песочницы действительно нет. Большую часть логики можно проверить без переводов (подпись, создание счёта, тестовые вебхуки), остальное — малыми суммами на дешёвой сети. → Тестирование интеграции
Только в личном кабинете под 2FA — в публичном API ротации нет. Заморозки выплат при ротации нет. → Безопасность в проде
Загляните в Справочник кодов ошибок и Глоссарий. Если проблема не про конкретный код, а про поведение — сверьтесь со страницей нужного метода в Справочнике.Если и это не помогло — создайте тикет в поддержку в кабинете my.oblodai.com (раздел «Поддержка»). Приложите ваш public_id, uuid платежа/выплаты и строки лога с префиксом oblodai: (в SDK включаются переменной OBLODAI_LOG, в модулях CMS — галочкой Debug log); secret не прикладывайте.

​
Связанные страницы

Справочник кодов ошибок

Глоссарий

Как подписать запрос

Отладка вебхуков

Тестирование интеграции

Что делать, если не работает