Формат и протокол
Конверт (envelope) — «обёртка» вокруг любого ответа API: полеstate (успех/ошибка), а полезные
данные лежат внутри result. → Формат взаимодействия
state — признак успеха ответа в конверте: 0 — всё хорошо (смотрите result); 1 (или наличие
поля error) — произошла ошибка.
unix‑секунды / unix‑время — способ записи момента времени числом: количество секунд, прошедших с
1 января 1970 года по UTC. Так задаётся, например, заголовок X-Timestamp и поле expired_at.
Heleket — другой платёжный API. «Heleket‑совместимый» означает, что формат запросов и ответов у
Oblodai совпадает с ним — чтобы миграцию можно было сделать почти без переписывания кода.
Best‑effort («по возможности») — операция выполняется, если получится, но её неуспех не ломает
основной процесс. Например, побочное уведомление могут отправить best‑effort: не дошло — платёж всё
равно засчитан.
Ключи и подпись
public_id — несекретный идентификатор вашего API‑ключа. Можно логировать. Уходит в заголовке
X-Public-Id. → Аутентификация
secret — секретная часть ключа, которой считается подпись запросов. Показывается один раз,
хранится только на сервере. Не путать с секретом вебхука.
Секрет вебхука — отдельный секрет, который возвращает /v1/webhooks;
им проверяется подпись входящих вебхуков. Это другое значение, чем secret API‑ключа.
HMAC‑SHA256 — алгоритм, которым считается подпись: хеш от строки на основе секрета. Используется и
для подписи запросов, и для подписи вебхуков — но по разным правилам сборки строки.
Каноническая строка — строго определённая строка, которую подписывают. Для запроса это
timestamp\nMETHOD\npath\nbody; для вебхука — timestamp.сырое_тело. → Как подписать
запрос
Идемпотентность — свойство операции, при котором повторный вызов не создаёт второй объект, а
возвращает существующий. Делает ретраи безопасными. В Oblodai работают два механизма сразу:
HTTP‑заголовок Idempotency-Key и ваш order_id. → Идемпотентность
Idempotency-Key — HTTP‑заголовок с любым уникальным значением (≤255 символов), который вы шлёте
на создающем запросе. Повтор с тем же значением вернёт тот же ответ (и заголовок
Idempotent-Replayed: true), а не создаст второй объект. Ключ генерируется до первой отправки и
одинаков во всех попытках. Если запрос с этим ключом ещё выполняется — 409 idempotency.in_progress.
Idempotent-Replayed — заголовок ответа: true означает, что ответ воспроизведён по
Idempotency-Key, новый объект не создавался.
Деньги
Валюта цены (currency) — валюта, в которой вы назначаете стоимость счёта. Это любой из
23 фиатов (USD, EUR, GBP, RUB, UAH, JPY, …) или любая монета. У JPY и KRW ноль
знаков после запятой. → Форматы сумм и денег
Валюта расчёта (to_currency) — монета, которой покупатель фактически платит и в которой вы
получаете деньги. Только крипта, фиат невозможен: шлюз не хранит фиат. Если цена в фиате и задана
network, но не задана to_currency, — ошибка payment.to_currency_required.
pricing_currencies — список валют цены (38 записей: 15 монет + 23 фиата) в ответе
GET /v1/currencies. Не путайте со списком currencies — тем, в чём можно
получать оплату (только крипта).
Единицы валюты — сумма в «человеческом» виде: "25.00" USDT = 25 USDT. Основной формат сумм в
API. → Форматы сумм и денег
Minor‑единицы (минимальные единицы) — сумма в наименьших неделимых долях валюты, строкой. Для USDT
(6 знаков) "18450000" = 18.45 USDT. Используется в отдельных полях (earnings_by_asset, min_minor)
— всегда оговаривается.
Комиссия платформы (наша комиссия) — то, что берёт Oblodai. По умолчанию 1.5 % + $0.30 с каждого
платежа (у приведённого реферала — 1.4 %). Удерживается и с инвойсов, и с депозитов на статический
кошелёк (со статических — только процент, без фиксированных $0.30).
Сетевая комиссия (газ) — плата сети блокчейна за транзакцию. Кто её несёт при выплате —
настраивается fee-config.
Dust / пыле‑порог — сумма настолько мелкая, что не покрывает даже сетевую комиссию за перевод.
Такие возвраты отклоняются кодом refund.dust, а выплаты — кодом payout.amount_below_fee: отправить их физически невозможно.
Курс — обменная котировка. У платежа фиксируется при создании и действует до rate_expires_at.
Публичные витринные котировки — /v1/exchange-rate/list.
Оракул курсов — сервис, который отдаёт актуальный курс криптовалюты. Именно от него берётся
котировка, когда сумма в вашей валюте пересчитывается в крипту.
subtract — устаревшее поле: процент сетевой наценки, перекладываемой на плательщика. Новичку не
нужно — payer‑facing наценки настраиваются через discount.
Приём платежей
Инвойс (счёт) — разовый платёжный объект на фиксированную сумму с ограниченным сроком. Создаётся/v1/payment. Оплата закрывает счёт. → Объект платежа
Статический кошелёк — постоянный адрес приёма без фиксированной суммы и срока; поступления падают
на баланс. Создаётся /v1/wallet. → Объект кошелька
Депозит‑адрес — адрес в блокчейне, на который покупатель отправляет оплату по счёту (поле
address). Именно его показывает hosted‑страница и QR‑код.
Hosted‑страница оплаты — страница Oblodai, куда вы отправляете покупателя по ссылке url. Показывает
адрес, QR, сумму, таймер и статус; работает без секрета мерчанта.
Валюто‑агностичный (deferred) счёт — счёт, у которого валюту и сеть выбирает покупатель на
hosted‑странице (is_multi: true). До выбора адрес и сумма пусты. → Три режима
order_id — ваш идентификатор заказа/операции. Служит ключом идемпотентности и связывает объект
Oblodai с вашим заказом.
uuid — идентификатор объекта (платежа, выплаты, кошелька) на стороне Oblodai.
Допуск (accuracy) — на сколько процентов недоплата всё ещё считается успешной оплатой. →
/v1/payment/accuracy
Недоплата / переплата — оплата меньше/больше ожидаемой суммы. Обрабатывается допуском и
автовозвратом. → Недоплата и переплата
Автовозврат (autorefund) — автоматический возврат излишка при переплате или суммы при истёкшей
недоплате. → /v1/payment/autorefund
payer_address — адрес, с которого пришли деньги. Это адрес возврата по умолчанию: возврат без
явного address уходит туда и авто‑подтверждается. Известен на аккаунтных сетях (EVM, Tron, Solana,
TON); на Bitcoin/UTXO пуст — там единого отправителя нет. → Объект платежа
refund_status — сводка по возвратам счёта: none (ничего не возвращали), partial (вернули
часть), full (вернули всё оплаченное). Приходит вместе с refunds[] в
/v1/payment/info.
Платёжная ссылка — многоразовый URL оплаты: каждый, кто по ней платит, получает свой отдельный
счёт. Единственный способ принимать платежи без своего бэкенда (Tilda, Wix, письмо): счёт создаёт
публичный POST /v1/link/{id}/checkout, подпись не нужна. → Платёжные ссылки
Донат (открытая сумма, amount_mode: "open") — режим платёжной ссылки, где сумму вводит сам
покупатель («заплати сколько хочешь»); amount_min — необязательный нижний порог. Соседние режимы:
fixed (сумму задали вы) и range (покупатель выбирает в диапазоне «от 5 до 1000»).
Чек (receipt) — письмо об успешной оплате. Уходит автоматически на payer_email, если тот
задан у платежа. Не путать с письмом «Оплатите» — его вы шлёте сами через
/v1/payment/send-email.
Массовые операции и сплиты
Батч (batch) — до 5000 операций (платежей, возвратов или выплат) в одном подписанном запросе. Обрабатывается асинхронно. Это штатный способ не упираться в лимит частоты: батч стоит один запрос, сколько бы элементов в нём ни было. →/v1/payment/batch
batch_id — идентификатор батча, который возвращается сразу при отправке. По нему статус и
результат каждого элемента забираются через /v1/batch/info. Статусы батча:
pending → processing → completed (последнее означает «обработка закончена», а не «всё успешно»).
on_error — поведение батча при ошибке элемента: continue (по умолчанию — обрабатывать
остальные) или stop (прекратить; оставшиеся элементы помечаются ошибкой).
Сплит (split) — правило, по которому доля каждого входящего платежа автоматически уходит партнёру
(например 10 % с каждого платежа). Для партнёрских программ и маркетплейсов. Сплит — пятый путь
ухода средств с баланса. → Сплит‑платежи
Refund‑hold (refund_hold_hours) — окно удержания: на сколько часов откладывается отправка долей
партнёрам. Смысл в том, что возврат списывает с вас всю сумму, которую заплатил покупатель, — если
доли разослать сразу, на возврат денег не останется. Пока окно не истекло, возврат отменяет или
уменьшает долю партнёра. Сплиты на внешний адрес после отправки необратимы; сплиты внутри
платформы (merchant_id) отзываются обратно. → /v1/split/config
Выплаты
Выплата (payout) — вывод средств с баланса на внешний адрес. → Объект выплаты Авто‑одобрение — выплаты по API‑ключу подтверждаются автоматически (approval_required: false) и
уходят сразу, без ручного шага.
maker‑checker — правило «создатель ≠ подтверждающий»: подтвердить выплату должен не тот, кто её
создал. Применяется к кабинетным сценариям; для API‑ключа не нужно. →
/v1/payout/approve
Автовывод (auto‑withdraw) — правило автоматически выводить чистую сумму депозита на заданный адрес.
→ /v1/auto-withdraw/*
Личный кошелёк — кошелёк владельца аккаунта, общий для всех его магазинов. По API доступен только
ввод средств в него; вывод — в кабинете под 2FA. → /v1/transfer/to-personal
Self‑dealing (выплата себе) — попытка вывести средства на адрес, который принадлежит самому шлюзу
Oblodai. Такая операция запрещена и отклоняется кодом payout.destination_internal (для возврата —
refund.destination_internal).
Kill‑switch (аварийная заморозка) — защитный механизм, который временно останавливает выплаты при
подозрительной активности. Пока он активен, выплаты возвращают код payout.frozen.
Co‑sign / 2‑of‑2 / awaiting_cosign — режим, где выплату должны подтвердить две стороны (нужна
вторая подпись). До второго подтверждения выплата стоит во внутреннем статусе awaiting_cosign.
Актуально только для мерчантов, у которых co‑sign включён обязательным; при обычном API‑ключе не
встречается.
Статусы и жизненный цикл
is_final — признак терминального статуса: объект больше не изменится.
Терминальный статус — конечное состояние объекта (для платежа: paid, paid_over,
wrong_amount, истёкший/отменённый; для выплаты: paid, fail, cancel).
Укрупнённый статус выплаты — Heleket‑совместимый статус в поле status (check/process/paid/
fail/cancel), в который сворачивается детальный внутренний жизненный цикл. →
Объект выплаты
Broadcasting — фаза, когда выплата уже отправляется в блокчейн и средства покидают горячий
кошелёк. Это один из внутренних статусов выплаты; наружу он сворачивается в укрупнённый process.
Блокчейн и безопасность
Подтверждения (confirmations) — число блоков, подтвердивших транзакцию. Порог зачёта зависит от суммы и сети (required_confirmations).
Reorg (реорганизация сети) — ситуация, когда сеть «переписывает» недавние блоки. Чтобы платёж не
откатился, средства выдерживаются до безопасной глубины.
txid — идентификатор (хеш) транзакции в блокчейне. По нему можно найти платёж или выплату в
обозревателе сети.
L2 / сеть второго уровня — надстройка над базовой сетью (например base, arbitrum над
Ethereum) с гораздо более дешёвыми комиссиями. Для приёма средств это такая же сеть, как и другие.
Незрелые (maturing) средства — депозит, уже зачисленный на баланс, но ещё не набравший
подтверждений и потому невыводимый. Выплата на такую сумму вернёт 409 payout.funds_maturing. →
/v1/balance
Maturity‑холд — временная задержка вывода незрелых средств ради reorg‑безопасности.
SSRF‑проверка — защита при регистрации URL вебхука: приватные и локальные адреса запрещены, чтобы
нельзя было заставить шлюз обращаться во внутреннюю сеть.
IP‑allowlist — список доверенных IP/CIDR; при включении запросы с других адресов отклоняются
(auth.ip_not_allowed). → IP‑allowlist
CIDR — компактная запись диапазона IP‑адресов, например 203.0.113.0/24 (весь блок адресов
203.0.113.*). Удобно, когда нужно разрешить сразу подсеть, а не один адрес.
Комплаенс‑скрининг — проверка адреса назначения на санкционные/рисковые списки перед выплатой или
возвратом.
VRCS (Volatility Risk Control System) — авто‑конвертация волатильных депозитов в USDT для защиты
от колебаний курса. → /v1/vrcs
Вебхуки
Вебхук (webhook) — HTTP‑уведомление, которое Oblodai шлёт на ваш URL при событии (оплата, пополнение, статус выплаты). → Объект вебхука at‑least‑once (как минимум один раз) — гарантия доставки: вебхук доставляется хотя бы раз, но может прийти и несколько раз. Отсюда требование дедупликации. Дедупликация — отбрасывание повторно пришедшего вебхука по пареuuid + status, чтобы не
обработать событие дважды.
transactional‑outbox — приём, при котором запись о доставке вебхука пишется в той же транзакции,
что и зачисление платежа, — уведомление не теряется.
dead‑letter (dead) — статус доставки, исчерпавшей все попытки. Виден в
журнале доставок.
Backoff (экспоненциальный) — стратегия повторов с растущей задержкой (10 с → удвоение → потолок
1 час). Применяется и к ретраям вебхуков, и рекомендуется вам при 5xx/503.