Что такое Oblodai
Oblodai — платёжный шлюз для приёма и отправки криптовалюты. Интеграция строится на двух вещах:- HTTP API — ваш backend вызывает его server‑to‑server, подписывая каждый запрос HMAC‑подписью. Через него вы создаёте платежи, получаете статусы, делаете выплаты и возвраты, управляете вебхуками.
- Hosted‑страница оплаты — при создании платежа шлюз возвращает ссылку/адрес, на который покупатель отправляет средства. Отслеживание поступления, подтверждения и переплаты/недоплаты берёт на себя шлюз, а вам присылает вебхук.
- Один API‑ключ на весь функционал — и приём, и выплаты. Радиус поражения ключа ограничен одним вашим мерчантом. За хранение ключа отвечаете вы.
- Всё server‑to‑server — секрет ключа считает подпись только на сервере и никогда не попадает в браузер или мобильное приложение. (Исключение — платёжные ссылки: они работают без вашего кода вообще, поэтому им сервер не нужен.)
- Идемпотентность — два механизма. HTTP‑заголовок
Idempotency-Key(одно значение на действие, неизменное во всех попытках; повтор вернёт тот же ответ) и вашorder_id, который тоже дедуплицирует (для выплат обязателен). Повторять запрос безопасно. → Устойчивый клиент
Начало работы
Регистрация и ключи
Начните отсюда: кабинет, ключи, что понадобится (сервер, вебхуки).
Быстрый старт
От получения ключей до первого вебхука за пять шагов.
Как подписать запрос
Разбор HMAC‑подписи по шагам и частые ошибки.
Сквозной пример приложения
Рабочий сервер приёма платежей целиком.
Тестирование интеграции
Как всё проверить без песочницы.
Приём платежей
Приём первого платежа
Создать счёт, показать адрес, дождаться оплаты.
Три режима создания счёта
Цена в фиате (23 валюты), выбор монеты покупателем, фиксированная валюта и сеть.
Платёжные ссылки
Оплата без своего бэкенда: донаты, диапазоны сумм, кнопка «Оплатить» на Tilda/Wix.
Недоплата, переплата и автовозврат
Настройки
accuracy и autorefund.Статические кошельки
Персональный постоянный адрес пополнения для клиента.
Счёт и чек на почту
Автоматический чек плательщику и отправка счёта письмом.
Модель баланса и движение средств
Откуда деньги приходят и куда уходят.
Выплаты и возвраты
Первая выплата
От баланса до подтверждающего вебхука.
Возвраты платежей
Полный и частичный; адрес указывать не обязательно.
Массовые выплаты: батч vs легаси /mass
/v1/payout/mass (до 100) — когда он ещё уместен; основной путь — батчи.Масштаб и автоматизация
Массовые операции (батчи)
До 5000 платежей, возвратов или выплат одним запросом — штатный способ не упираться в rate limit.
Сплит‑платежи
Доля каждого платежа автоматически уходит партнёрам. Для партнёрок и маркетплейсов.
Вебхуки
Настройка и приём вебхуков
Регистрация, проверка подписи, идемпотентность обработчика.
Отладка вебхуков
Тестовые события, журнал доставок, переотправка.
Безопасность вебхуков
Replay‑защита и перепроверка статуса — за пределами подписи.
Прод и надёжность
Рецепт устойчивого клиента
Таймауты, идемпотентность, ретраи, backoff. Какие
409 надо повторять, а какие нет.Безопасность в проде
Хранение ключа, IP‑allowlist, ротация ключа.
Чек‑лист перед запуском
Что проверить до боевого трафика.
FAQ и диагностика
Частые вопросы — короткие ответы.
Что делать, если не работает
Пошаговая диагностика по симптому.
Миграция
Переход с Heleket на Oblodai
Отличия API и что поправить в коде.