> ## Documentation Index > Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Глоссарий Термины, которые встречаются в документации Oblodai. Если по ходу чтения попался незнакомый термин — он, скорее всего, здесь. *** ## Формат и протокол **Конверт (envelope)** — «обёртка» вокруг любого ответа API: поле `state` (успех/ошибка), а полезные данные лежат внутри `result`. → [Формат взаимодействия](/reference/basics-format) **`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`. → [Аутентификация](/reference/basics-auth) **`secret`** — секретная часть ключа, которой считается подпись запросов. Показывается один раз, хранится только на сервере. Не путать с секретом вебхука. **Секрет вебхука** — отдельный секрет, который возвращает [`/v1/webhooks`](/reference/webhooks-register); им проверяется подпись **входящих** вебхуков. Это другое значение, чем `secret` API‑ключа. **HMAC‑SHA256** — алгоритм, которым считается подпись: хеш от строки на основе секрета. Используется и для подписи запросов, и для подписи вебхуков — но по **разным** правилам сборки строки. **Каноническая строка** — строго определённая строка, которую подписывают. Для запроса это `timestamp\nMETHOD\npath\nbody`; для вебхука — `timestamp.сырое_тело`. → [Как подписать запрос](/guides/signing-requests) **Идемпотентность** — свойство операции, при котором повторный вызов не создаёт второй объект, а возвращает существующий. Делает ретраи безопасными. В Oblodai работают **два механизма сразу**: HTTP‑заголовок `Idempotency-Key` и ваш `order_id`. → [Идемпотентность](/reference/basics-idempotency) **`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` ноль знаков после запятой. → [Форматы сумм и денег](/reference/basics-money) **Валюта расчёта** (`to_currency`) — монета, которой покупатель **фактически платит** и в которой вы получаете деньги. **Только крипта, фиат невозможен**: шлюз не хранит фиат. Если цена в фиате и задана `network`, но не задана `to_currency`, — ошибка `payment.to_currency_required`. **`pricing_currencies`** — список валют цены (38 записей: 15 монет + 23 фиата) в ответе [`GET /v1/currencies`](/reference/currencies). Не путайте со списком `currencies` — тем, в чём можно **получать** оплату (только крипта). **Единицы валюты** — сумма в «человеческом» виде: `"25.00"` USDT = 25 USDT. Основной формат сумм в API. → [Форматы сумм и денег](/reference/basics-money) **Minor‑единицы (минимальные единицы)** — сумма в наименьших неделимых долях валюты, строкой. Для USDT (6 знаков) `"18450000"` = 18.45 USDT. Используется в отдельных полях (`earnings_by_asset`, `min_minor`) — всегда оговаривается. **Комиссия платформы (наша комиссия)** — то, что берёт Oblodai. По умолчанию 1.5 % + \$0.30 с каждого платежа (у приведённого реферала — 1.4 %). Удерживается и с инвойсов, и с депозитов на статический кошелёк (со статических — только процент, без фиксированных \$0.30). **Сетевая комиссия (газ)** — плата сети блокчейна за транзакцию. Кто её несёт при выплате — настраивается [`fee-config`](/reference/payout-fee-config). **Dust / пыле‑порог** — сумма настолько мелкая, что не покрывает даже сетевую комиссию за перевод. Такие возвраты отклоняются кодом `refund.dust`, а выплаты — кодом `payout.amount_below_fee`: отправить их физически невозможно. **Курс** — обменная котировка. У платежа фиксируется при создании и действует до `rate_expires_at`. Публичные витринные котировки — [`/v1/exchange-rate/list`](/reference/exchange-rate-list). **Оракул курсов** — сервис, который отдаёт актуальный курс криптовалюты. Именно от него берётся котировка, когда сумма в вашей валюте пересчитывается в крипту. **`subtract`** — устаревшее поле: процент сетевой наценки, перекладываемой на плательщика. Новичку не нужно — payer‑facing наценки настраиваются через [`discount`](/reference/payment-discount). *** ## Приём платежей **Инвойс (счёт)** — разовый платёжный объект на фиксированную сумму с ограниченным сроком. Создаётся [`/v1/payment`](/reference/payment-create). Оплата закрывает счёт. → [Объект платежа](/reference/payment-object) **Статический кошелёк** — постоянный адрес приёма без фиксированной суммы и срока; поступления падают на баланс. Создаётся [`/v1/wallet`](/reference/wallet-create). → [Объект кошелька](/reference/wallet-object) **Депозит‑адрес** — адрес в блокчейне, на который покупатель отправляет оплату по счёту (поле `address`). Именно его показывает hosted‑страница и QR‑код. **Hosted‑страница оплаты** — страница Oblodai, куда вы отправляете покупателя по ссылке `url`. Показывает адрес, QR, сумму, таймер и статус; работает без секрета мерчанта. **Валюто‑агностичный (deferred) счёт** — счёт, у которого валюту и сеть выбирает покупатель на hosted‑странице (`is_multi: true`). До выбора адрес и сумма пусты. → [Три режима](/guides/payment-modes) **`order_id`** — ваш идентификатор заказа/операции. Служит ключом идемпотентности и связывает объект Oblodai с вашим заказом. **`uuid`** — идентификатор объекта (платежа, выплаты, кошелька) на стороне Oblodai. **Допуск (accuracy)** — на сколько процентов недоплата всё ещё считается успешной оплатой. → [`/v1/payment/accuracy`](/reference/payment-accuracy) **Недоплата / переплата** — оплата меньше/больше ожидаемой суммы. Обрабатывается допуском и автовозвратом. → [Недоплата и переплата](/guides/under-overpayment) **Автовозврат (autorefund)** — автоматический возврат излишка при переплате или суммы при истёкшей недоплате. → [`/v1/payment/autorefund`](/reference/payment-autorefund) **`payer_address`** — адрес, **с которого пришли деньги**. Это адрес возврата по умолчанию: возврат без явного `address` уходит туда и авто‑подтверждается. Известен на аккаунтных сетях (EVM, Tron, Solana, TON); на Bitcoin/UTXO пуст — там единого отправителя нет. → [Объект платежа](/reference/payment-object) **`refund_status`** — сводка по возвратам счёта: `none` (ничего не возвращали), `partial` (вернули часть), `full` (вернули всё оплаченное). Приходит вместе с `refunds[]` в [`/v1/payment/info`](/reference/payment-info). **Платёжная ссылка** — многоразовый URL оплаты: каждый, кто по ней платит, получает свой отдельный счёт. **Единственный способ принимать платежи без своего бэкенда** (Tilda, Wix, письмо): счёт создаёт публичный `POST /v1/link/{id}/checkout`, подпись не нужна. → [Платёжные ссылки](/reference/payment-link) **Донат (открытая сумма, `amount_mode: "open"`)** — режим платёжной ссылки, где сумму вводит сам покупатель («заплати сколько хочешь»); `amount_min` — необязательный нижний порог. Соседние режимы: `fixed` (сумму задали вы) и `range` (покупатель выбирает в диапазоне «от 5 до 1000»). **Чек (receipt)** — письмо об успешной оплате. Уходит **автоматически** на `payer_email`, если тот задан у платежа. Не путать с письмом «Оплатите» — его вы шлёте сами через [`/v1/payment/send-email`](/reference/payment-send-email). *** ## Массовые операции и сплиты **Батч (batch)** — до **5000** операций (платежей, возвратов или выплат) в **одном** подписанном запросе. Обрабатывается асинхронно. Это **штатный способ не упираться в [лимит частоты](/reference/basics-ratelimit)**: батч стоит один запрос, сколько бы элементов в нём ни было. → [`/v1/payment/batch`](/reference/payment-batch) **`batch_id`** — идентификатор батча, который возвращается сразу при отправке. По нему статус и результат каждого элемента забираются через [`/v1/batch/info`](/reference/batch-info). Статусы батча: `pending` → `processing` → `completed` (последнее означает «обработка закончена», а не «всё успешно»). **`on_error`** — поведение батча при ошибке элемента: `continue` (по умолчанию — обрабатывать остальные) или `stop` (прекратить; оставшиеся элементы помечаются ошибкой). **Сплит (split)** — правило, по которому доля каждого входящего платежа автоматически уходит партнёру (например 10 % с каждого платежа). Для партнёрских программ и маркетплейсов. Сплит — **пятый путь** ухода средств с баланса. → [Сплит‑платежи](/reference/split-rule) **Refund‑hold (`refund_hold_hours`)** — окно удержания: на сколько часов откладывается отправка долей партнёрам. Смысл в том, что **возврат списывает с вас всю сумму, которую заплатил покупатель**, — если доли разослать сразу, на возврат денег не останется. Пока окно не истекло, возврат отменяет или уменьшает долю партнёра. Сплиты на внешний адрес после отправки **необратимы**; сплиты внутри платформы (`merchant_id`) отзываются обратно. → [`/v1/split/config`](/reference/split-config) *** ## Выплаты **Выплата (payout)** — вывод средств с баланса на внешний адрес. → [Объект выплаты](/reference/payout-object) **Авто‑одобрение** — выплаты по API‑ключу подтверждаются автоматически (`approval_required: false`) и уходят сразу, без ручного шага. **maker‑checker** — правило «создатель ≠ подтверждающий»: подтвердить выплату должен не тот, кто её создал. Применяется к кабинетным сценариям; для API‑ключа не нужно. → [`/v1/payout/approve`](/reference/payout-approve) **Автовывод (auto‑withdraw)** — правило автоматически выводить чистую сумму депозита на заданный адрес. → [`/v1/auto-withdraw/*`](/reference/auto-withdraw) **Личный кошелёк** — кошелёк владельца аккаунта, общий для всех его магазинов. По API доступен только ввод средств в него; вывод — в кабинете под 2FA. → [`/v1/transfer/to-personal`](/reference/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`), в который сворачивается детальный внутренний жизненный цикл. → [Объект выплаты](/reference/payout-object#статусы-выплаты) **Broadcasting** — фаза, когда выплата уже отправляется в блокчейн и средства покидают горячий кошелёк. Это один из внутренних статусов выплаты; наружу он сворачивается в укрупнённый `process`. *** ## Блокчейн и безопасность **Подтверждения (confirmations)** — число блоков, подтвердивших транзакцию. Порог зачёта зависит от суммы и сети (`required_confirmations`). **Reorg (реорганизация сети)** — ситуация, когда сеть «переписывает» недавние блоки. Чтобы платёж не откатился, средства выдерживаются до безопасной глубины. **`txid`** — идентификатор (хеш) транзакции в блокчейне. По нему можно найти платёж или выплату в обозревателе сети. **L2 / сеть второго уровня** — надстройка над базовой сетью (например `base`, `arbitrum` над Ethereum) с гораздо более дешёвыми комиссиями. Для приёма средств это такая же сеть, как и другие. **Незрелые (maturing) средства** — депозит, уже зачисленный на баланс, но ещё не набравший подтверждений и потому невыводимый. Выплата на такую сумму вернёт `409 payout.funds_maturing`. → [`/v1/balance`](/reference/balance) **Maturity‑холд** — временная задержка вывода незрелых средств ради reorg‑безопасности. **SSRF‑проверка** — защита при регистрации URL вебхука: приватные и локальные адреса запрещены, чтобы нельзя было заставить шлюз обращаться во внутреннюю сеть. **IP‑allowlist** — список доверенных IP/CIDR; при включении запросы с других адресов отклоняются (`auth.ip_not_allowed`). → [IP‑allowlist](/reference/api-allowlist) **CIDR** — компактная запись диапазона IP‑адресов, например `203.0.113.0/24` (весь блок адресов `203.0.113.*`). Удобно, когда нужно разрешить сразу подсеть, а не один адрес. **Комплаенс‑скрининг** — проверка адреса назначения на санкционные/рисковые списки перед выплатой или возвратом. **VRCS (Volatility Risk Control System)** — авто‑конвертация волатильных депозитов в USDT для защиты от колебаний курса. → [`/v1/vrcs`](/reference/vrcs) *** ## Вебхуки **Вебхук (webhook)** — HTTP‑уведомление, которое Oblodai шлёт на ваш URL при событии (оплата, пополнение, статус выплаты). → [Объект вебхука](/reference/webhook-object) **at‑least‑once (как минимум один раз)** — гарантия доставки: вебхук доставляется хотя бы раз, но может прийти и несколько раз. Отсюда требование дедупликации. **Дедупликация** — отбрасывание повторно пришедшего вебхука по паре `uuid` + `status`, чтобы не обработать событие дважды. **transactional‑outbox** — приём, при котором запись о доставке вебхука пишется в той же транзакции, что и зачисление платежа, — уведомление не теряется. **dead‑letter (`dead`)** — статус доставки, исчерпавшей все попытки. Виден в [журнале доставок](/reference/webhooks-deliveries). **Backoff (экспоненциальный)** — стратегия повторов с растущей задержкой (10 с → удвоение → потолок 1 час). Применяется и к ретраям вебхуков, и рекомендуется вам при `5xx`/`503`. *** ## Связанные страницы