# Журнал изменений API

Все изменения публичного API: новые маршруты, поля, события вебхуков и коды ошибок. Новые записи добавляются сверху, даты указаны по UTC. Изменение, ломающее совместимость, отмечается словом **несовместимо** и объясняет, что должен сделать интегратор.

## 2026-10-14, сумма в стейблкоине не пересчитывается, прежняя сумма засчитывается 10 минут

- **Токен, привязанный к доллару США** (`USDT_*`, `USDC_*`): сумма инвойса с ценой в долларах, зафиксированная при выборе, действует до дедлайна инвойса и после окна котировки больше не пересчитывается, остаток после частичной оплаты — тоже. `quote.expires_at` у такого инвойса равен `expires_at` инвойса, в том числе у инвойса, выбранного раньше. Раньше сумма сдвигалась на центы каждые 30 минут, и покупатель, заплативший ровно показанное, получал `partially_paid`.
- **Остальные токены** пересчитываются после окна, как раньше, но перевод в блоке не позже 10 минут после конца окна прежней котировки оценивается и по её сумме. Если он её покрыл, инвойс становится `confirmed`, а `amount_requested`, `amount_expected` и `quote` (с её `number`) — снова те, что у прежней котировки. См. [окно котировки](https://stons.io/ru/docs/invoices.md#окно-котировки).
- Поля и коды ошибок не менялись.

## 2026-10-14, остаток меньше минимального депозита оплачивает инвойс

- Перевод меньше минимального депозита актива больше не теряется, если это остаток инвойса `per_invoice`: когда по инвойсу уже пришёл платёж, а `amount_expected` ещё не набран, перевод в активе инвойса на его адрес — платёж (`kind: payment`) любой суммы больше нуля. Раньше он становился пылью, и инвойс, которому не хватало центов, оставался `underpaid`. См. [частичная оплата](https://stons.io/ru/docs/invoices.md#частичная-оплата).
- Первый перевод по инвойсу, перевод после того, как сумма набрана, нулевой перевод и перевод на адрес `per_user` меньше минимального депозита — по-прежнему пыль.
- Поля и коды ошибок не менялись.

## 2026-10-14, нативная монета из смарт-контракта засчитывается

- **Нативная монета EVM-сети, которую отправил смарт-контракт, теперь засчитывается** — со смарт-кошелька, мультиподписи, вывода с биржи: она оплачивает инвойс, попадает в ответ `GET /v1/deposits/{tx_hash}` и даёт вебхуки `deposit.*`, как обычный перевод с кошелька. Сервис находит такой перевод трейсом блока и засчитывает, только если трейс объясняет весь рост баланса адреса; перевод, который объяснить не удалось, по-прежнему разбирает оператор, — см. [что приходит на адрес](https://stons.io/ru/docs/addresses.md#что-приходит-на-адрес).
- У такого перевода `log_index` = `-2`, `-3` и далее, как уже у перевода, сделанного контрактом в TRON. В одной транзакции их может быть несколько, и рядом — её собственная сумма с `-1`. **Проверьте интеграцию**, если она считает, что `log_index` нативной монеты всегда `-1` или что транзакция платит адресу один раз.
- Маршруты, поля, тела вебхуков и коды ошибок не менялись. Решение — ADR-0055.

## 2026-10-14, страница оплаты оценивает ожидание подтверждений

- **Новое поле `confirmation_estimate` в `GET /checkout/v1/invoices/{id}`** и в ответе `POST /checkout/v1/invoices/{id}/select`: пока перевод ждёт подтверждений — сколько блоков ему ещё нужно, сколько это секунд по времени блока сети и ждёт ли сеть ещё и окончательного блока ([страница оплаты](https://stons.io/ru/docs/checkout.md#прочитать-инвойс-для-страницы)). Страница показывает это как «Осталось около N минут», а не обещает около минуты в любой сети.

## 2026-10-14, у нативной монеты нет стандарта токенов

- **`token_standard` — `null` у нативной монеты** в `GET /checkout/v1/invoices/{id}` и в ответе `POST /checkout/v1/invoices/{id}/select`, и у инвойса, и у каждого элемента `choices`: BNB — не токен BEP-20, SOL — не токен SPL ([страница оплаты](https://stons.io/ru/docs/checkout.md#прочитать-инвойс-для-страницы)). Раньше поле называло стандарт сети для любого актива.

## 2026-10-06, цена в долларах в выбранной монете

- **Новое поле `price_currency` в `POST /v1/invoices`.** Единственное значение — `USD`, и только вместе с `asset`. С ним `amount` — цена в долларах, а не количество монет: сервис сам пересчитывает её в названный актив по своему курсу (ADR-0070, [цена в долларах в выбранной монете](https://stons.io/ru/docs/invoices.md#цена-в-долларах-в-выбранной-монете)).
- **Ответ на создание сразу готов к оплате:** `address`, `amount_expected`, `price`, `quote.rate` и `expires_at` приходят в ответе на `POST`, без страницы оплаты и без выбора покупателя.
- **Поле необязательное, прежний смысл сохранён:** без `price_currency` `amount` по-прежнему сумма в единицах актива. Существующие интеграции менять не нужно.
- `price_currency` без `asset` отклоняется (`400 validation_failed`): там `amount` и так цена в долларах.
- **Курс недоступен — инвойс не создаётся:** `503 rate_unavailable`, и в базе ничего не остаётся.
- **Новый маршрут `GET /v1/rates`:** по каждому активу проекта курс, по которому будет посчитан инвойс (рыночный за вычетом наценки сервиса), сам рыночный курс, процент наценки, время наблюдения и признак свежести. Чтобы «≈ 0,45 SOL» рядом с ценой совпадало с суммой инвойса.

## 2026-10-05, интеграция настраивает проект своим ключом

- **Новые маршруты** `GET` и `PATCH /v1/project`, `GET` и `PUT /v1/project/assets`. Интеграция — или ассистент, которому дали один ключ API — сама указывает адрес вебхука, адреса возврата и принимаемые токены. В кабинет для этого заходить не нужно (ADR-0067, [аутентификация](https://stons.io/ru/docs/authentication.md#настройки-проекта)).
- **Секрет подписи вебхуков эти маршруты не возвращают.** Он показывается один раз, при создании проекта; ключ API — не доступ к секрету.
- **Адрес вебхука можно задать и заменить, но не удалить:** `null` — `400`. События, уже поставленные в очередь, должны куда-то уходить.
- Режим адресов и режим хранения средств этими маршрутами не меняются: их разрешает оператор.

## 2026-10-05, режим адресов разрешается по проектам

- **Новый код ошибки `422 mode_not_allowed`** на `POST /v1/addresses`, `POST /v1/invoices` и `POST /checkout/v1/invoices/{id}/select`: режим адресов этого проекта ему не разрешён. Оператор разрешает ограниченный режим по проектам, а не всей платформе сразу (ADR-0066). Прежний `422 address_mode_disabled` остался и значит другое: платформа приостановила режим для всех.
- **Режим адресов проекта стало можно менять.** Раньше он выбирался один раз при создании. Теперь оператор разрешает режим, и владелец проекта переключается на него в кабинете. Смена решает, где будет собран следующий платёж, и никогда — где собран прежний: уже выданные адреса остаются при своём, зачисляются и переносятся как раньше.
- **Создать проект сразу в `per_user` из кабинета нельзя:** `422 mode_not_allowed`. Создавайте в `per_invoice` и переключайтесь после того, как оператор разрешит режим.

## 2026-10-05, Solana

Solana — четвёртое семейство сетей, с которым работает сервис. Ни один маршрут, ни одно поле и ни одно событие вебхука не изменили форму; изменился набор сетей и активов, которые они несут.

- **Приём платежей работает в десяти сетях:** к `tron`, `ethereum`, `bsc`, `polygon`, `base`, `arbitrum`, `optimism`, `avalanche` и `ton` добавилась `solana`. Её активы — `USDT_SOLANA`, `USDC_SOLANA` и нативная монета `SOL_SOLANA`, каждому нужно 1 подтверждение; mint'ы и число знаков — в [активах Solana](https://stons.io/ru/docs/invoices.md#активы-solana).
- **Выплат в Solana нет**, как нет их в EVM-сетях и TON: `422 asset_not_payable`.
- **`tx_hash` перевода в Solana — не шестнадцатеричный хэш.** Это первая подпись транзакции: 86–88 знаков base58, у которых регистр несёт смысл и должен сохраняться. В колонку, рассчитанную на 64 шестнадцатеричных знака, она не поместится, а приведение к нижнему регистру уничтожает значение. Это касается `GET /v1/deposits/{tx_hash}`, поля `deposits` инвойса и вебхуков `deposit.*` — см. [адреса в Solana](https://stons.io/ru/docs/addresses.md#адреса-в-solana).
- **Адрес Solana — тоже base58 из 32–44 знаков и тоже регистрозависим.** Храните, сравнивайте и показывайте его ровно таким, каким его вернул API; регистр не нормализуйте никогда.
- `wallet_url` на странице оплаты в Solana остаётся `null`: ссылку-диплинк кошелька сервис собирает только в TON — см. [прочитать инвойс для страницы](https://stons.io/ru/docs/checkout.md#прочитать-инвойс-для-страницы).
- Токен в Solana лежит в associated token account, а не на самом адресе; этот аккаунт сервис создаёт и наблюдает сам. Кошелёк покупателя платит на адрес как обычно, а код, который проверяет платёж чтением цепи, должен знать: `getSignaturesForAddress` на адрес перевода SPL не покажет.

## 2026-10-05, какие сети и токены работают на самом деле

Запись исправляет документацию, а не поведение API: ни один маршрут и ни одно поле не менялись. Прежние записи журнала говорили, что EVM-сети в разработке, а TON планируется; это перестало быть правдой раньше, чем документация это отразила.

- **Приём платежей работает в девяти сетях:** `tron`, `ethereum`, `bsc`, `polygon`, `base`, `arbitrum`, `optimism`, `avalanche`, `ton`. Их активы перечисляет `GET /v1/assets`, контракты и число знаков — в [активах](https://stons.io/ru/docs/invoices.md#активы).
- **Нативные монеты принимаются** наравне с токенами, по курсу: `TRX_TRON`, `GRAM_TON`, `ETH_ETHEREUM`, `BNB_BSC`, `POL_POLYGON`, `ETH_BASE`, `ETH_ARBITRUM`, `ETH_OPTIMISM`, `AVAX_AVALANCHE`. Засчитывается только обычный перевод с кошелька.
- **USDT в Polygon, Arbitrum и OP Mainnet — это USDT0**, отдельный актив с собственным контрактом: `USDT0_POLYGON`, `USDT0_ARBITRUM`, `USDT0_OPTIMISM`.
- **`USDC_TRON` выключен оператором целиком**, а не только для новых счетов: выплаты в нём тоже выключены и отклоняются с `422 asset_payouts_disabled`. Документация до этой записи обещала, что выплаты в нём работают, — это было неверно.
- **Выплаты по-прежнему только в сети TRON**, и только в `USDT_TRON`. В EVM-сетях и TON выплат нет: `422 asset_not_payable`.
- Список сетей и токенов больше не описывается статусами «работает / в разработке / планируется»: [сети и токены](https://stons.io/ru/docs/networks.md) говорят, что сервис делает в каждой сети, а что доступно проекту в данный момент — ответ `GET /v1/assets`. Актив, выключенный оператором или настройками проекта, в этом ответе не появляется.

## 2026-10-05, кошелёк сборов виден в API

- API кабинета: у объекта проекта появилось `custody_mode` — `custodial` (деньги хранит сервис) или `pass_through` (деньги идут на кошелёк самого проекта). Меняет его только оператор.
- API кабинета: `GET /cabinet/v1/merchants/{id}/settlement-wallets` отдаёт кошельки проекта, на которые пересылаются принятые средства, по одному на актив: адрес целиком, с какого момента он годен и годен ли уже. У кастодиального проекта список пуст. См. куда уходят деньги.
- Административный API: `GET /admin/v1/merchants/{id}/settlement-wallets` отдаёт то же плюс кто внёс запись и отпечаток ключа, которым она подписана.
- API мерчантов и тела вебхуков не изменились. Запись кошелька по-прежнему делается командой с подписью оператора, а не через API.

## 2026-10-05, некастодиальный режим в административном API

- Административный API: у объекта мерчанта появилось `custody_mode` — `custodial` (наше хранилище) или `pass_through` (кошелёк сборов самого мерчанта). `PATCH /admin/v1/merchants/{id}` его принимает; перевод в `pass_through` без действующего кошелька сборов отвечает `422 settlement_wallet_missing`.
- Административный API: `GET /admin/v1/custody-modes` и `PATCH /admin/v1/custody-modes/{mode}` — тумблер сквозного режима на платформе. Кастодиальный режим выключить нельзя: `422 custody_mode_last_enabled`.
- API мерчантов, API кабинета и тела вебхуков не изменились. Кошелёк, на который пересылаются деньги мерчанта, вносит оператор подписью вне сервиса, а не через API.
- Для интеграций описано: что значит `settled` у проекта с прямыми сборами, почему его баланс остаётся нулевым и что мелкие платежи копятся на адресе приёма, пока перевод не начнёт стоить своих затрат, — см. [куда уходят деньги](https://stons.io/ru/docs/invoices.md#куда-уходят-деньги).

## 2026-10-04, баланс проекта по API

- API мерчантов: `GET /v1/balance` отдаёт баланс по реестру каждого актива, в котором у проекта что-то есть, рядом — что ещё не подтверждено, и те же деньги в долларах по принятым сервисом курсам. Актив без свежего курса попадает в список и в `total.unpriced_assets`, а не оценивается по устаревшему. В ответе есть `ETag`. См. [баланс](https://stons.io/ru/docs/balance.md).
- Ни один существующий маршрут или поле не изменились.

## 2026-10-04, QR-код инвойса и условные чтения

- API мерчантов: `POST /v1/invoices` и `GET /v1/invoices/{id}` принимают параметр строки запроса `include=qr` и тогда отдают `qr.address` — QR-код адреса оплаты в виде SVG-картинки в `data:`-ссылке, около 11 КБ. Это та же картинка, которую рисует страница оплаты, поэтому продукту, который рисует свою страницу оплаты, библиотека QR не нужна. Без параметра поля нет; лента изменений этот параметр не принимает. См. [QR-код](https://stons.io/ru/docs/invoices.md#qr-код).
- API мерчантов: `GET /v1/assets`, `GET /v1/invoices`, `GET /v1/invoices/{id}` и `GET /v1/deposits/{tx_hash}` отвечают заголовком `ETag`. Запрос, который вернул его в `If-None-Match`, получает `304 Not Modified` без тела, пока ответ не изменился; `*` совпадает всегда. Ошибки метки не получают. См. [условные чтения](https://stons.io/ru/docs/authentication.md#условные-чтения).
- **Ломающее** для клиента, который присылал свои параметры строки запроса: `POST /v1/invoices` и `GET /v1/invoices/{id}` теперь принимают только `include` и отклоняют любой другой параметр с `400 validation_failed`. В документации таких параметров не было; клиенту, который добавлял к этим двум адресам свои метки, нужно перестать.

## 2026-10-04, лента изменений инвойсов

- API мерчантов: `GET /v1/invoices` отдаёт инвойсы проекта в порядке изменения состояния — догон после пропущенного вебхука. Параметры `updated_since`, `status`, `limit` (1–100, по умолчанию 50) и `cursor`; в ответе `invoices` без поля `deposits` и `next_cursor`. Страницы keyset'ом: инвойс, изменившийся во время обхода, страницу не сдвигает. См. [ленту изменений](https://stons.io/ru/docs/invoices.md#лента-изменений).
- Прежние маршруты и поля не изменились.

## 2026-10-04, шаг суммы у токена, привязанного к доллару

- API мерчантов: сумма инвойса в токене, привязанном к доллару, округляется вверх до цента этого токена, а не до его последнего знака. Цена $229.00 при курсе 0.9999 просит `229.03`, а не `229.024488`. Округление по-прежнему вверх: покупатель платит не меньше цены, разница меньше цента и в пользу мерчанта. У токенов, не привязанных ни к чему, шаг прежний — 0.00000001 единицы. Так же шагает остаток, пересчитанный после истечения окна котировки. См. [цену и курс](https://stons.io/ru/docs/invoices.md#цена-и-курс) и ADR-0053.
- Поля и коды ошибок не изменились.

## 2026-10-04, реквизиты оплаты для своей страницы

- API мерчантов: в ответе инвойса появилось поле `payment_uri` — ссылка, открывающая кошелёк с заполненным переводом. Она есть, пока запрошена точная сумма: инвойс ждёт денег, дедлайн не прошёл и котировка держится. Сейчас ссылку даёт только TON; у остальных сетей `null`, потому что схемы ссылок, которой сервис доверяет, там нет.
- API мерчантов: в `GET /v1/assets` появились `confirmations` — сколько подтверждений нужно переводу в активе, и `icon` — метка актива в каталоге. По ним мерчант рисует «2 из 20» и список монет на своей странице оплаты, не придумывая эти значения.
- Совместимость сохранена: прежние поля не изменились и не исчезли.
- Внутренние маршруты первичной настройки `/setup/*` убраны из `GET /v1/openapi.json`: документ описывает только маршруты самого мерчанта.

## 2026-09-20, отметка строки вывода выплаченной вручную

- Административный API: `POST /admin/v1/withdrawals/{id}/lines/{line_id}/force-paid` отмечает строку заявки выплаченной, не дожидаясь подтверждения из цепи, с обязательной причиной. Это единственное решение сотрудника по заявке, которое двигает деньги: проводится то же, что провела бы сверка, и теми же ключами. В объекте заявки у строк появились `forced_by`, `forced_at` и `force_reason`. См. вывод средств мерчанта и ADR-0058.
- API мерчантов, API кабинета и тела вебхуков не изменились.

## 2026-09-20, плата за вывод в долларах

- Административный API: `POST /admin/v1/withdrawal-fees` и `POST /admin/v1/merchants/{id}/withdrawal-fees` принимают `amount_usd` вместо `amount` — фиксированную часть в долларах. Сервис переводит её в монету по свежему курсу при каждой заявке и замораживает в строке; сумма в монете хранится рядом и действует, когда свежего курса нет. В ответе у действующей платы и у строк тарифа появилось поле `amount_usd`. Без свежего курса запись такой строки отвечает `503 rate_unavailable`. См. плата за вывод средств и ADR-0059.
- API мерчантов, API кабинета и тела вебхуков не изменились. Совместимость административного API сохранена: `amount` по-прежнему принимается.

## 2026-09-20, своя плата за вывод

- Административный API: у платы за вывод средств мерчанта свой тариф — `GET /admin/v1/withdrawal-fees`, `POST /admin/v1/withdrawal-fees`, `GET /admin/v1/merchants/{id}/withdrawal-fees`, `POST /admin/v1/merchants/{id}/withdrawal-fees` — и оверрайд по отдельному проекту. Новые коды ошибок `withdrawal_fee_confirmation_required` и `withdrawal_fee_valid_from_in_past` — см. плата за вывод средств. Решение — ADR-0059.
- **Несовместимо** для клиентов административного API, которые задавали плату за вывод через `POST /admin/v1/payout-fees`: теперь это только тариф выплат третьим лицам, а плату за вывод задают маршруты выше. История прежнего тарифа перенесена в новый, поэтому действующие числа не изменились.
- API мерчантов, API кабинета и тела вебхуков не изменились.

## 2026-09-19, вывод средств мерчанта

- API кабинета: заявки на вывод средств проекта на кошельки владельца — `GET /cabinet/v1/withdrawals/assets`, `GET /cabinet/v1/withdrawals`, `POST /cabinet/v1/withdrawals/preview`, `POST /cabinet/v1/withdrawals`, `GET /cabinet/v1/withdrawals/{id}`, `POST /cabinet/v1/withdrawals/{id}/cancel`. В заявке несколько токенов и кошельков, суммы с платами откладываются сразу, создание требует подтверждённого кабинетом кода второго фактора — см. вывод средств. Решение — ADR-0058.
- Административный API: `GET /admin/v1/withdrawals/summary`, `GET /admin/v1/withdrawals`, `GET /admin/v1/withdrawals/{id}`, внесение хэша ручного перевода `POST /admin/v1/withdrawals/{id}/lines/{line_id}/tx` и отказы `POST /admin/v1/withdrawals/{id}/lines/{line_id}/reject`, `POST /admin/v1/withdrawals/{id}/reject` — см. вывод средств мерчанта. Тариф выплат `POST /admin/v1/payout-fees` задаётся любому активу каталога, а не только тому, где есть выплаты: он же — плата за вывод; `GET /admin/v1/payout-fees` перечисляет все действующие активы.
- Новые коды ошибок этих маршрутов: `withdrawal_not_found`, `withdrawal_insufficient_balance`, `withdrawal_not_cancelable`, `withdrawal_line_not_found`, `withdrawal_line_not_open`, `withdrawal_tx_in_use`, `withdrawal_code_required`.
- API мерчантов и тела вебхуков не изменились.

## 2026-09-19, средства в долларах в кабинете

- API кабинета: `GET /cabinet/v1/balances` возвращает рядом с `balances` новые поля `assets`, `projects` и `total`. Это балансы по активам всех проектов, по проектам и в сумме, с оценкой в долларах США по рыночному курсу. Актив без свежего курса в суммы не входит и перечислен в `unpriced_assets` — см. API кабинета.
- API мерчантов, тела вебхуков и коды ошибок не изменились.

## 2026-09-18, TON

- Новая сеть `ton` — боевая сеть TON с активами `USDT_TON` (6 знаков) и `GRAM_TON` — Gram, нативная монета TON (9 знаков). `USDT_TON` оплачивает инвойсы; `GRAM_TON` — после того как платформа включит приём в нём, как `TRX_TRON`. Выплат в TON нет. `GET /v1/assets` перечисляет активы TON, когда оператор включит сеть, — см. [сети и токены](https://stons.io/ru/docs/networks.md) и [активы](https://stons.io/ru/docs/invoices.md#активы).
- **Адрес в TON возвращается в user-friendly форме**: 48 символов base64url, без флага bounce — `UQ…`, в тестовой сети `0Q…`. В этой форме `address` приходит в `POST /v1/addresses`, в инвойсах, в `GET /v1/deposits/{tx_hash}` и в вебхуках `deposit.*`, и так его показывают покупателю, ничего не меняя, — см. [адреса в TON](https://stons.io/ru/docs/addresses.md#адреса-в-ton). `contract` токена TON в `GET /v1/assets` — мастер-контракт жетона в raw-форме: `0:` и 64 шестнадцатеричные цифры. **Проверьте интеграцию**, если она сверяет адрес с формами TRON и EVM-сетей: форму TON тоже нужно принимать.
- Хэш транзакции TON — 64 шестнадцатеричных символа без `0x`, как в TRON; `GET /v1/deposits/{tx_hash}` его принимает. В TON `log_index` у перевода токена `0`, у перевода GRAM `-1` — см. [проверить перевод](https://stons.io/ru/docs/addresses.md#проверить-перевод).
- Маршруты страницы оплаты отдают новое поле `wallet_url`: в TON — ссылку `ton://transfer`, которая открывает приложение кошелька с адресом, оставшейся суммой и токеном; в других сетях `null`. Страница показывает её кнопкой «Открыть в кошельке» — см. [прочитать инвойс для страницы](https://stons.io/ru/docs/checkout.md#прочитать-инвойс-для-страницы). Мерчантам эти маршруты не нужны.
- Административный API: семейство `ton`, у которого `chain_id` — глобальный идентификатор сети; `chain_symbol` в предпросмотре токена бывает `null`, если жетон хранит символ вне цепи; мастер-контракт жетона TON принимается в raw-форме и в user-friendly; порог газового кошелька и `gas_wallet` есть и у TON — см. административный API.
- Коды ошибок и тела вебхуков `invoice.*` не изменились.

## 2026-09-16, платежи в нативных монетах EVM-сетей

- Платформа может принимать к оплате нативные монеты EVM-сетей — `ETH_ETHEREUM`, `BNB_BSC`, `POL_POLYGON`, `ETH_BASE`, `ETH_ARBITRUM`, `ETH_OPTIMISM`, `AVAX_AVALANCHE`, — когда включит их сеть и приём в них. Они ведут себя как `TRX_TRON`: цена по курсу, `GET /v1/assets` перечисляет их, пока в них можно выставить инвойс, 18 знаков, выплат нет — см. [сети и токены](https://stons.io/ru/docs/networks.md) и [активы](https://stons.io/ru/docs/invoices.md#активы). EVM-сети по-прежнему в разработке.
- **Засчитывается только обычный перевод с кошелька.** Монета, отправленная смарт-контрактом (смарт-кошельком, некоторыми биржами), автоматически не засчитывается, не попадает в ответ `GET /v1/deposits/{tx_hash}`, и вебхука нет — см. [что приходит на адрес](https://stons.io/ru/docs/addresses.md#что-приходит-на-адрес).
- У перевода такой монеты `log_index` = `-1` в `GET /v1/deposits/{tx_hash}` и в вебхуках `deposit.*`, как уже у перевода TRX. **Проверьте интеграцию**, если она считает, что `log_index` не бывает отрицательным.
- Маршруты, поля, тела вебхуков и коды ошибок не изменились. Административный API: `PATCH /admin/v1/assets/{id}` включает `accepts_payments` у нативной монеты EVM-сети вместе с её `rate_symbol`, и `payments_supported` у неё — `true`, — см. административный API. Решение — ADR-0055.

## 2026-09-16, платежи в TRX

- Платформа может принимать к оплате `TRX_TRON` — нативную монету TRON, когда платформа включает приём в нём. `GET /v1/assets` перечисляет `TRX_TRON`, пока в нём можно выставить инвойс: список берите оттуда — см. [список активов](https://stons.io/ru/docs/invoices.md#список-активов) и [активы](https://stons.io/ru/docs/invoices.md#активы).
- Такие инвойсы и выбор работают так же, как у любого актива, цена в который переводится по курсу. Инвойс, созданный без `asset` и оплачиваемый в `TRX_TRON`, переводится по курсу, пониженному на наценку платформы, а остаток долга после окна котировки пересчитывается — см. [цену и курс](https://stons.io/ru/docs/invoices.md#цена-и-курс). У инвойса, созданного с `asset` = `TRX_TRON`, сумма в TRX, её задаёт мерчант.
- Выплаты в `TRX_TRON` невозможны: `POST /v1/payouts` отвечает `422 asset_not_payable`.
- **Проверьте интеграцию**, если она сверяет `asset` инвойса, перевода или вебхука с фиксированным перечнем: примите `TRX_TRON`. Число знаков берите из `GET /v1/assets`, а не из кода.
- Маршруты, поля, тела вебхуков и коды ошибок не изменились. Административный API: `PATCH /admin/v1/assets/{id}` включает `accepts_payments` у `TRX_TRON`, а для нативной монеты EVM-сети и для снятия `rate_symbol` у актива, принимаемого без привязки к доллару США, отвечает `409 asset_flag_locked` — см. административный API. Решение — ADR-0054.

## 2026-09-16, цены в долларах США по курсу

- Инвойс, созданный без `asset`, переводится в выбранный токен по курсу, который собирает сервис, в том числе стейблкоин: 1 USDT больше не считается равным 1 USD. Сумма округляется вверх до последнего знака токена, а у токена, у которого знаков больше 8, — до 8 знаков, поэтому покупатель платит не меньше цены. Токен, не привязанный к доллару США, переводится по курсу, пониженному на наценку платформы. См. [цену и курс](https://stons.io/ru/docs/invoices.md#цена-и-курс); решение — ADR-0053.
- **Несовместимо** для кода, который сравнивает свою цену с `amount_requested` инвойса, созданного без `asset`: цена, переведённая по курсу, не равна `price.amount`. Сравнивайте с `price.amount`.
- **Несовместимо** для кода, который читает `amount_expected` или `amount_remaining` такого инвойса один раз. После окна котировки, пока инвойс в статусе `created` или `partially_paid` и дедлайн не прошёл, остаток долга пересчитывается по текущему курсу, и эти суммы и `amount_requested` меняются. Вебхука об этом нет: читайте суммы из `GET /v1/invoices/{id}`. См. [окно котировки](https://stons.io/ru/docs/invoices.md#окно-котировки).
- Цена, которая не записывается в токене точно, больше не отклоняется с `400 validation_failed`: она округляется вверх.
- Новое поле `quote` в ответах `POST /v1/invoices` и `GET /v1/invoices/{id}`: `rate`, `market_rate`, `markdown_percent`, `currency`, `number` и `expires_at`. Оно `null` у инвойса, созданного с `asset`, до выбора и у инвойса, токен которого выбран до этого изменения. См. [котировку](https://stons.io/ru/docs/invoices.md#котировка).
- **Проверьте интеграцию** на новый код ошибки: `POST /v1/invoices` без `asset` отвечает `503 rate_unavailable`, когда ни у одного разрешённого токена нет свежего курса, и инвойс не создаётся. Повторите позже с тем же `order_id`. `422 asset_not_offered` теперь значит, что у токена из `currencies` нет курса, а `422 no_payable_assets` — что мерчант не принимает ни одного токена с курсом. См. [коды ошибок](https://stons.io/ru/docs/errors.md#перечень).
- Маршруты страницы оплаты: `GET /checkout/v1/invoices/{id}` отдаёт `rate`, `rate_id` и `rate_expires_at` в каждом элементе `choices`, а у инвойса — `rates_unavailable` и `quote` с `rate`, `currency` и `expires_at`. `POST /checkout/v1/invoices/{id}/select` принимает необязательный `rate_id` и может ответить `503 rate_unavailable`. См. [сохранение выбора токена](https://stons.io/ru/docs/checkout.md#сохранить-выбор-токена). Мерчантам эти маршруты не нужны.
- API кабинета: `quote` у инвойсов; `POST /cabinet/v1/invoices` может ответить `503 rate_unavailable`. Административный API: `quote` у инвойсов, новые маршруты `GET /admin/v1/rates` и `PATCH /admin/v1/rates/settings` и поле актива `rate_symbol` — см. административный API.
- Тела вебхуков не изменились. Инвойсы, созданные с `asset`, работают как раньше.

## 2026-09-14, газовый кошелёк в реестре

- Административный API: новый вид счёта реестра `gas_wallet` в `GET /admin/v1/balances` и в проводках `GET /admin/v1/ledger/transactions` — газовый кошелёк EVM-сети в её нативной монете. Проводка газа переноса в хранилище — `reason` = `fee`, ключ `sweep_gas:{network}:{tx_hash}`: дебет `network_fees`, кредит `gas_wallet`. См. административный API.
- Публичный API, вебхуки и коды ошибок не изменились.

## 2026-09-14, управление сетями и токенами

- Административный API управляет сетями и токенами — административный API. Новые маршруты: `POST /admin/v1/networks`, `PATCH /admin/v1/networks/{id}`, `GET /admin/v1/networks/{id}/tokens/{contract}`, `POST /admin/v1/assets` и `DELETE /admin/v1/assets/{id}`. `PATCH /admin/v1/assets/{id}` меняет ещё минимумы, подтверждения, порог свипа, флаги приёма и выплат, архив и знак, а `GET /admin/v1/assets` принимает параметр `network`.
- Новые поля в ответах административного API: у сети — `icon_slug` и `rpc_configured`, у актива — `pegged_to`, `sweep_min_amount`, `icon_slug` и `payouts_supported`. Новые коды ошибок: `asset_exists`, `asset_in_use`, `asset_referenced`, `asset_confirmations_below_finality`, `asset_symbol_required`, `contract_invalid`, `contract_not_token`, `network_not_found`, `network_exists`, `network_without_assets`, `network_family_not_supported`, `network_rpc_not_configured`, `network_chain_id_mismatch`, `network_rpc_unavailable`.
- Маршруты страницы оплаты `GET /checkout/v1/invoices/{id}` и `POST /checkout/v1/invoices/{id}/select` отдают `network_icon_slug` — slug знака сети — у инвойса и в каждом элементе `choices`, см. [прочитать инвойс для страницы](https://stons.io/ru/docs/checkout.md#прочитать-инвойс-для-страницы). API мерчантов не изменился. Новые EVM-сети появляются в реестре выключенными, и их активы мерчантам не предлагаются.

## 2026-09-14, список активов, хэши EVM-сетей, ссылки на обозреватель

- Новые поля с названием сети и ссылками на её обозреватель. Инвойсы (`POST /v1/invoices`, `GET /v1/invoices/{id}`): `network_name`, `address_explorer_url` и `explorer_url` в каждом элементе `deposits`. `GET /v1/deposits/{tx_hash}`: `explorer_url`. Выплаты: `network_name` и `explorer_url`. Ссылка собирается из шаблона обозревателя сети и равна `null`, если шаблона у сети нет — см. [создать инвойс](https://stons.io/ru/docs/invoices.md#создать-инвойс).
- Маршрут страницы оплаты `GET /checkout/v1/invoices/{id}` отдаёт `address_explorer_url` и `explorer_url` в `deposits`, а `address` — в том виде, в каком его видит покупатель: в EVM-сетях с контрольной суммой EIP-55 — см. [прочитать инвойс для страницы](https://stons.io/ru/docs/checkout.md#прочитать-инвойс-для-страницы). API мерчанта отдаёт EVM-адреса в нижнем регистре.

- Новый маршрут `GET /v1/assets`: активы, в которых мерчант может выставить инвойс сейчас, с `network`, `network_name`, `token_standard`, `contract`, `decimals` и `min_amount`. По нему решают, какие токены предложить, вместо списка в коде — см. [список активов](https://stons.io/ru/docs/invoices.md#список-активов).
- `GET /v1/deposits/{tx_hash}` принимает и хэш в форме EVM-сетей: `0x` и 64 шестнадцатеричных символа. Хэш ищется ровно в той форме, в которой передан, в любом регистре; хэш TRON по-прежнему пишется без `0x` — см. [проверить перевод](https://stons.io/ru/docs/addresses.md#проверить-перевод).
- EVM-сети по-прежнему в разработке: пока оператор не включил ни одной, `GET /v1/assets` перечисляет только активы TRON, и для интеграции с TRON ничего не меняется. Коды ошибок не изменились.

## 2026-09-14, сеть в событиях вебхуков

- Новое поле `network` в `data` событий `invoice.*` и `deposit.*`: идентификатор сети актива, например `tron`, — то же значение, что `network` инвойса и перевода в API. В `invoice.expired` инвойса, покупатель которого не выбрал токен, оно `null`. См. [вебхуки](https://stons.io/ru/docs/webhooks.md#тело).
- Поле добавлено, ничего не удалено и не переименовано. **Проверьте интеграцию**, если она отклоняет неизвестные поля в теле вебхука: примите `network`.
- Сервис готовится принимать платежи в EVM-сетях, где один хэш транзакции может быть в нескольких сетях. Перевод определяют `network`, `tx_hash` и `log_index` вместе.
- Маршруты и коды ошибок не изменились.

## 2026-09-14, USDC в TRON только для выплат

- **Проверьте интеграцию**, если она создаёт инвойсы в `USDC_TRON` или передаёт его в `currencies`. Circle прекратила выпуск USDC в сети TRON, и оператор выключил приём в `USDC_TRON`: `POST /v1/invoices` в этом активе и с ним в `currencies` отвечает `422 asset_payments_disabled`. Уберите актив из запросов или обрабатывайте этот код. См. [активы](https://stons.io/ru/docs/invoices.md#активы).
- Страница оплаты не предлагает `USDC_TRON` покупателю, а `POST /v1/addresses` не включает его в `assets`.
- Выплаты в `USDC_TRON` работают. Уже открытые инвойсы в `USDC_TRON` оплачиваются, а перевод USDC на постоянный адрес `per_user` зачисляется, как раньше.
- Маршруты, поля и коды ошибок не изменились. Обоснование — ADR-0026, поправка от 2026-09-14.

## 2026-09-14, частичная оплата

- Новый статус инвойса `partially_paid`: до дедлайна подтверждённые переводы покрыли часть `amount_expected`, и ни один перевод не ждёт подтверждений. Покупатель может дослать остаток на тот же адрес до дедлайна. Допуска недоплаты нет: `confirmed` по-прежнему означает всю сумму, а после дедлайна без остатка приходит `underpaid`. См. [частичную оплату](https://stons.io/ru/docs/invoices.md#частичная-оплата).
- Новое событие вебхука `invoice.partially_paid` — при каждом переходе в этот статус. См. [события](https://stons.io/ru/docs/webhooks.md#события).
- Новое поле `amount_remaining` в ответах `POST /v1/invoices` и `GET /v1/invoices/{id}`: `amount_expected` минус `amount_received`, не меньше нуля; `null`, пока покупатель не выбрал токен. То же поле — в ответе маршрута страницы оплаты `GET /checkout/v1/invoices/{id}`.
- **Несовместимо** для кода, который разбирает `status` или тип события строгим перечнем. Раньше частично оплаченный инвойс до дедлайна оставался `seen`; теперь он `partially_paid`, а `seen` означает, что перевод ждёт подтверждений. Добавьте `partially_paid` в перечень и не отдавайте при нём товар. На `invoice.partially_paid`, если обработчик его не обрабатывает, отвечайте `2xx`.
- **Проверьте интеграцию.** Кнопка «Вернуться в магазин» ведёт на `cancel_url` и со `status=partially_paid`: инвойс открыт и ещё может быть оплачен — см. [переход до исхода](https://stons.io/ru/docs/checkout.md#переход-до-исхода).
- Страница оплаты при `partially_paid` просит дослать `amount_remaining` на тот же адрес, а при `seen` больше не пишет, что ничего отправлять не нужно. См. [страницу оплаты](https://stons.io/ru/docs/checkout.md#страница-для-покупателя).
- API кабинета и административный API: `partially_paid` среди статусов инвойса и в фильтре `status`. Коды ошибок не изменились.

## 2026-09-14, проверка перевода и пауза режима адресов

- Новый маршрут `GET /v1/deposits/{tx_hash}`: переводы транзакции на адреса мерчанта с `kind`, `status`, `confirmations` и `credited`. Пополнение `per_user` без инвойса теперь проверяется через API, как требует главное правило вебхуков, — см. [проверку перевода](https://stons.io/ru/docs/addresses.md#проверить-перевод). Новый код `404 deposit_not_found`.
- **Проверьте интеграцию.** Платформа может приостановить режим адресов. Пока режим на паузе, его проекты получают `422 address_mode_disabled` от `POST /v1/addresses`, `POST /v1/invoices` и `POST /checkout/v1/invoices/{id}/select`, а новый проект не может выбрать этот режим, — см. [режим на паузе](https://stons.io/ru/docs/addresses.md#режим-на-паузе). Переводы на уже выданные адреса зачисляются как обычно. Обрабатывайте код как любой другой `422`: сообщите покупателю, что оплата сейчас недоступна.
- API кабинета: `GET /cabinet/v1/address-modes`; `POST /cabinet/v1/merchants` и `POST /cabinet/v1/invoices` могут ответить `422 address_mode_disabled`. Административный API: `GET /admin/v1/address-modes` и `PATCH /admin/v1/address-modes/{mode}`, код `422 address_mode_last_enabled` — административный API.

## 2026-09-13, событие о неудавшейся выплате

- Вебхук `payout.failed` приходит при каждом переходе выплаты в `failed`. Раньше — только когда сканер находил её транзакцию неуспешной. Теперь ещё: когда сервер подписи отказался её подписывать; когда попытки исчерпаны; когда неуспешную транзакцию прежней попытки нашёл сам сервер подписи. Событие одно на выплату. См. [события](https://stons.io/ru/docs/webhooks.md#события).
- **Несовместимо** для кода, который разбирает `payout.failed` строго: `tx_hash` в нём бывает `null` — у выплаты, для которой ничего не подписывалось. Поле `reason` — текст для человека.
- Выплата больше не становится `failed`, если узел ответил на отправку её транзакции ошибкой или не ответил вовсе: деньги могли уйти. Она остаётся в `queued` с тем же `tx_hash`, пока транзакция не найдётся в цепи или не истечёт, не попав в блок. См. [статусы выплат](https://stons.io/ru/docs/payouts.md#статусы).
- Маршруты и коды ошибок не изменились.

## 2026-09-13, документация на английском

- Документация публикуется на двух языках. Английская — основная, по прежним адресам: `/docs`, `/docs/<раздел>.md`, `/llms.txt` и `/llms-full.txt`. Русская — под `/ru`: `/ru/docs`, `/ru/docs/<раздел>.md`, `/ru/llms.txt` и `/ru/llms-full.txt`. Интеграциям, которые читают русский Markdown по прежним адресам, нужно перейти на адреса с `/ru`.
- Страница оплаты открывается на языке покупателя: параметр `lang` в `checkout_url`, затем выбор покупателя на странице, затем язык браузера, иначе английский. См. [страницу оплаты](https://stons.io/ru/docs/checkout.md#страница-для-покупателя).
- API, коды ошибок и события вебхуков не изменились.

## 2026-09-13, токен выбирает покупатель

- `asset` в `POST /v1/invoices` стал необязательным. Без него токен и сеть выбирает покупатель на странице оплаты, а `amount` — цена в долларах США. Новое необязательное поле `currencies` — из каких активов выбирать. См. [токен выбирает покупатель](https://stons.io/ru/docs/invoices.md#токен-выбирает-покупатель), решение — ADR-0042.
- У инвойса новые поля `price`, `currencies` и `asset_selected_at`.
- **Несовместимо** для кода, который разбирает инвойсы строго. У инвойса без выбранного токена равны `null`:
  - `asset`, `network`, `address`;
  - `amount_requested`, `amount_expected`, `amount_received`, `amount_credited`;
  - `fees.service.fixed` и `fees.service.amount`.

  Интеграции, которые всегда передают `asset`, таких инвойсов не создают, и менять им ничего не нужно. Те же `null` — в событии `invoice.expired` инвойса, срок которого вышел без выбора, и в ответах API кабинета и консоли.
- Повтор `POST /v1/invoices` без `asset` сравнивает цену и набор `currencies`: другой набор — `409 order_id_conflict`.
- Новые коды: `422 asset_required`, `422 no_payable_assets`, `422 asset_not_offered`; у маршрута страницы оплаты ещё `409 asset_already_selected` и `409 invoice_expired`.
- Маршрут страницы оплаты `GET /checkout/v1/invoices/{id}`: поля `price` и `choices`, поля актива и сумм допускают `null`. Новый маршрут `POST /checkout/v1/invoices/{id}/select`. Мерчантам они не нужны.
- `POST /cabinet/v1/invoices`: `asset` необязателен, новое поле `currencies`.
- Административный API: в инвойсе поля `price`, `currencies` и `asset_selected_at`; актив, адрес и суммы допускают `null`.

## 2026-09-13, срок инвойса и адреса возврата

- `expires_in` в `POST /v1/invoices` стал необязательным: без него инвойс ждёт платежа 3600 секунд (1 час).
- **Несовместимо** для запросов со сроком меньше 5 минут или больше 72 часов. Границы `expires_in` теперь от 300 до 259200 секунд — в `POST /v1/invoices` и в `POST /cabinet/v1/invoices`. Раньше были от 60 до 604800 (7 дней). Запрос вне границ получает `400 validation_failed`, в том числе повтор запроса, принятого раньше: форма проверяется до поиска инвойса. Если интеграция ставит срок больше 72 часов, уменьшите его. Уже созданные инвойсы сохраняют свой срок.
- Переопределения `return_url` и `cancel_url` в `POST /v1/invoices` допускаются и в пределах сайта проекта из заявки (`site_url`): origin должен совпасть с адресом проекта того же вида или с сайтом проекта. На `t.me` и `telegram.me` совпасть должно и имя бота или канала — первый сегмент пути, без учёта регистра; это же правило теперь действует и для адреса проекта того же вида. Раньше без адреса того же вида в настройках проекта переопределение отклонялось с `422 redirect_url_not_allowed`. Требования к форме адреса не изменились — см. [адреса возврата](https://stons.io/ru/docs/checkout.md#адреса-возврата).
- **Проверьте интеграцию.** Пока инвойс можно оплатить, страница оплаты показывает кнопку «Вернуться в магазин», если у инвойса или проекта есть адрес отмены. Кнопка ведёт на `cancel_url` с подписью и `status=created` или `status=seen`: инвойс при этом открыт и ещё может быть оплачен. Если обработчик адреса отмены отменяет заказ, пусть сначала проверит статус через `GET /v1/invoices/{id}` — см. [переход до исхода](https://stons.io/ru/docs/checkout.md#переход-до-исхода). Сама страница, пока инвойс открыт, никуда не переводит.
- `POST /cabinet/v1/invoices`: необязательные `return_url` и `cancel_url` по тем же правилам.
- Маршрут страницы оплаты `GET /checkout/v1/invoices/{id}`: новое поле `back_url` — подписанный адрес для кнопки «Вернуться в магазин».
- Соответствие параметров Heleket — в [странице оплаты](https://stons.io/ru/docs/checkout.md#если-вы-переходите-с-heleket).

## 2026-09-13, процент и фиксированная сумма комиссий

- У комиссии сервиса инвойса появилась фиксированная сумма по активу. Новое поле `fees.service.fixed` — сумма, записанная в инвойс при создании; `fees.service.amount` — по-прежнему всё удержанное, теперь это процент и фиксированная сумма вместе. Поля только добавлены. То же — в данных событий `invoice.*`, в ответах API кабинета и страницы оплаты. См. [комиссии](https://stons.io/ru/docs/invoices.md#комиссии).
- **Проверьте интеграцию.** Если комиссию сервиса платит покупатель, `amount_expected` = цена + процент + фиксированная сумма. Сравнивайте свою цену с `amount_requested`, как и раньше. Пока оператор фиксированную сумму не задал, она равна нулю, и ничего не меняется.
- Фиксированная сумма удерживается один раз на инвойс и не больше полученного: платёж меньше неё удерживается целиком. Пополнение `per_user` без инвойса — отдельная операция со своей фиксированной суммой.
- У комиссии выплаты появился процент от суммы: новые поля `fees.network.percent` и `fees.network.fixed`, а `fees.network.amount` — вся комиссия, фиксированная сумма плюс процент от `amount`, округлённый вниз. То же — в данных событий `payout.confirmed` и `payout.failed`. См. [комиссию за выплату](https://stons.io/ru/docs/payouts.md#комиссия-за-выплату).
- Административный API: маршруты `GET /admin/v1/invoice-fees` и `POST /admin/v1/invoice-fees`, коды `invoice_fee_confirmation_required` и `invoice_fee_valid_from_in_past` — административный API. **Несовместимо** для клиентов административного API: `POST /admin/v1/payout-fees` требует поле `percent` и принимает `confirm_high_rate`, а в ответе у действующей комиссии и у строк тарифа появилось поле `percent`. Консоль обновлена в том же изменении.

## 2026-09-13, комиссия сети

- **Несовместимо** для кода, который проверяет `fees.network.status` инвойса по перечню `quoted`, `pending`, `settled`. У инвойса нет отдельной комиссии сети: затраты сети на приём входят в комиссию сервиса, и `fees.network.status` теперь всегда `included`. Прежние значения больше не приходят. Ключи сохранены: `quote`, `quote_rate` и `actual` — всегда `null`, `payer` — всегда `merchant`. Если интеграция проверяет перечень строго, добавьте `included`. См. [комиссии](https://stons.io/ru/docs/invoices.md#комиссии). То же — в событиях `invoice.*` и в ответах API кабинета и страницы оплаты.
- Коды `422 network_fee_payer_not_supported` и `503 network_fee_quote_unavailable` остаются: покупатель комиссию сети не несёт. Изменились только их сообщения.
- У выплаты новое поле `fees.network`: `payer` — всегда `merchant`, `amount` — фиксированная комиссия сети, записанная в выплату при создании, `charged` — сколько списано с баланса проекта. То же — в данных событий `payout.confirmed` и `payout.failed`. См. [комиссию за выплату](https://stons.io/ru/docs/payouts.md#комиссия-за-выплату).
- Комиссия сети списывается с баланса проекта при подтверждении выплаты, отдельной проводкой реестра; выплата, провалившаяся в цепи, её не несёт. Получатель по-прежнему получает ровно `amount`.
- Административный API: тариф комиссии сети за выплату — `GET /admin/v1/payout-fees` и `POST /admin/v1/payout-fees`, коды `payout_fee_confirmation_required` и `payout_fee_valid_from_in_past`; новый вид счёта реестра `network_cost_recovery` в `GET /admin/v1/balances` и в проводках — административный API.

## 2026-09-13, комиссия сервиса

- У инвойса новые поля: `amount_requested` — цена мерчанта, `amount_credited` — полученное за вычетом удержанных комиссий, `fees` — комиссия сервиса и комиссия сети. Поля только добавлены, прежние не меняют смысла: `amount_expected` — по-прежнему сумма, которую должен заплатить покупатель. См. [комиссии](https://stons.io/ru/docs/invoices.md#комиссии).
- **Проверьте интеграцию.** Если в проекте комиссию сервиса платит покупатель, `amount_expected` больше цены на эту комиссию. Код, который сравнивает `amount_expected` со своей ценой заказа, должен сравнивать `amount_requested`. В проектах, где комиссию платит мерчант (так по умолчанию), `amount_expected` равен цене, как раньше.
- Идемпотентность `POST /v1/invoices` по `order_id` сравнивает `amount` запроса с ценой `amount_requested`: повтор присылает цену, а не сумму с комиссией.
- Комиссия сервиса удерживается с каждого подтверждённого платежа отдельной проводкой реестра и уменьшает баланс мерчанта. Ставка записывается в инвойс при создании: смена тарифа не меняет уже выставленные инвойсы.
- Те же поля — в данных событий `invoice.*` ([вебхуки](https://stons.io/ru/docs/webhooks.md#тело)) и в ответе маршрута страницы оплаты; страница оплаты показывает разбивку «Цена · Комиссия сервиса · Итого», когда комиссию платит покупатель ([страница оплаты](https://stons.io/ru/docs/checkout.md)).
- Новый код `503 network_fee_quote_unavailable`: проект настроен так, что комиссию сети платит покупатель, а посчитать её сейчас нельзя. Такую настройку API кабинета больше не принимает — `422 network_fee_payer_not_supported`.
- Административный API: тарифы комиссии сервиса — `GET /admin/v1/service-fees`, `POST /admin/v1/service-fees/platform`, `GET /admin/v1/merchants/{id}/service-fees`, `POST /admin/v1/merchants/{id}/service-fees`, коды `service_fee_confirmation_required` и `service_fee_valid_from_in_past` — административный API. `GET /admin/v1/fees` остался отчётом о комиссиях сети.

## 2026-09-13, проверка проектов и настройки проекта

- Проект, который бизнес заводит сам, принимает платежи только после проверки. Пока он не одобрен или если отклонён, `POST /v1/invoices` и `POST /v1/addresses` отвечают новым кодом `403 merchant_not_approved`. Ключи API при этом работают, чтение инвойсов тоже. Все мерчанты, созданные раньше, одобрены: для существующих интеграций ничего не меняется.
- Владелец может выключить приём в активе для своего проекта. Тогда `POST /v1/invoices` в этом активе отвечает новым кодом `422 asset_disabled_by_merchant`, а `POST /v1/addresses` не включает актив в список `assets`. Уже открытые инвойсы оплачиваются и закрываются, повтор принятого запроса возвращает инвойс.
- `403 merchant_disabled` теперь означает выключение и оператором, и владельцем проекта.
- Проект без адреса вебхуков событий не получает: они не ставятся в очередь и после появления адреса не досылаются ([вебхуки](https://stons.io/ru/docs/webhooks.md#доставка)).
- Административный API: у мерчанта новые поля — `review_status`, `review_reason`, `reviewed_at`, `reviewed_by`, `site_url`, `description`, `network_fee_payer`, `service_fee_payer`, `disabled_by`. Появились фильтр `GET /admin/v1/merchants?review_status=`, маршруты `POST /admin/v1/merchants/{id}/approve` и `POST /admin/v1/merchants/{id}/reject` — административный API. **Несовместимо** для клиентов административного API: `webhook_url` мерчанта может быть `null`. Консоль обновлена в том же изменении.
- Маршруты `/cabinet/v1` для приложения кабинета: служебные, снаружи недоступны и в `GET /v1/openapi.json` не входят.

## 2026-09-13, переключатели приёма и выплат

- Оператор может временно выключить приём или выплаты в активе. Пока приём выключен, `POST /v1/invoices` в этом активе отвечает новым кодом `422 asset_payments_disabled`, а `POST /v1/addresses` не включает актив в список `assets`. Пока выключены выплаты, `POST /v1/payouts` отвечает новым кодом `422 asset_payouts_disabled`.
- Повторы запросов, принятых раньше, отвечают как прежде: инвойс по тому же `order_id` и выплата по тому же `reference` возвращаются.
- Уже открытые инвойсы оплачиваются и закрываются, уже созданные выплаты исполняются: переключатель касается только нового.
- Административный API: `PATCH /admin/v1/assets/{id}`, поля `payments_enabled` и `payouts_enabled` в объекте актива, новые коды `asset_not_found` и `asset_flag_locked` — административный API.

## 2026-09-13, административный API консоли

- Маршруты `/admin/v1` для консоли оператора: мерчанты и их ключи, инвойсы, остатки счетов реестра, движение средств, комиссии сети, каталог активов, доставки вебхуков и журнал аудита — административный API. Доступ по токену консоли `ADMIN_API_TOKEN` и заголовку оператора `X-Operator`; без токена маршрутов нет (ADR-0033).
- Адреса возврата мерчанта `return_url` и `cancel_url` видны в объекте мерчанта и меняются `PATCH /admin/v1/merchants/{id}` по правилам [страницы оплаты](https://stons.io/ru/docs/checkout.md#адреса-возврата).
- Новые коды ошибок, только у этих маршрутов: `merchant_not_found`, `api_key_not_found`, `delivery_not_found`, `delivery_not_failed`.
- Маршруты `/v1` и описание `GET /v1/openapi.json` не изменились: административные маршруты в него не входят.

## 2026-09-13, страница оплаты и адреса возврата

- У инвойса новое поле `checkout_url` — ссылка на [страницу оплаты](https://stons.io/ru/docs/checkout.md), если оператор её настроил, иначе `null`.
- Необязательные поля `return_url` и `cancel_url` в `POST /v1/invoices`: куда страница оплаты вернёт покупателя. Допускаются только в пределах origin адресов, заданных у мерчанта оператором; иначе новый код `422 redirect_url_not_allowed`. Те же поля появились в ответе инвойса.
- Повтор `POST /v1/invoices` с другими `return_url` или `cancel_url` — `409 order_id_conflict`, как повтор с другой суммой. Запросы без этих полей ведут себя как раньше.
- Возврат покупателя подписан: параметры `invoice_id`, `order_id`, `status`, `ts`, `signature`, подпись HMAC-SHA256 секретом вебхуков. Формат и код проверки — в [странице оплаты](https://stons.io/ru/docs/checkout.md#подпись). Решение — ADR-0032.
- `GET /checkout/v1/invoices/{id}` — служебный маршрут сервера страницы оплаты, без ключа API, в приватной сети. Мерчантам он не нужен.

## 2026-09-12, USDC в сети TRON

- Новый актив `USDC_TRON`: инвойсы и выплаты в USDC принимаются наравне с USDT, 6 знаков после запятой, 20 подтверждений. Контракт `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` — прочитан в сети, а не взят из статьи: `symbol() = USDC`, `name() = USD Coin`, `decimals() = 6`. Обоснование и граница решения — в ADR-0026.
- USDC на адресе приёма больше **не** считается неожиданным активом сам по себе. `unexpected_asset` — актив каталога, который адрес не принимает: на адресе инвойса — актив, отличный от актива инвойса, на постоянном адресе — актив, не принимаемый к оплате (TRX). Токен, которого нет в каталоге, не записывается вовсе. Первая редакция этого пункта называла `unexpected_asset` токеном вне каталога; это было неверно и исправлено 2026-09-14.
- TRX платёжным активом пока **не** стал: в режиме сжигания энергии (`SWEEP_ENERGY_MODE=burn`) комиссию за свип платит сам адрес приёма, поэтому TRX на него кладёт оператор — и с включённым флагом эти операционные деньги были бы зачислены как чей-то платёж. Сначала правило, отличающее переводы с наших адресов, и тест; потом флаг. Выплаты в TRX не появятся и после: суточные лимиты складывают суммы в одной единице, что верно только для привязанных к доллару активов.
- Активы тестовых сетей не изменились: проверяемого контракта USDC в Nile и Shasta нет.

## 2026-09-12, домен в установщике

- `POST /setup/domain` — панель находит у провайдера DNS зону, которой принадлежит указанное имя, создаёт или исправляет запись A на адрес этого сервера и возвращает то, что видно в публичном DNS прямо сейчас. Проверяется **не своя запись, а ответ сети**: записанное и видимое — разные утверждения, и работает только второе.
- Если зоны у провайдера нет, панель **создаёт её сама** и показывает NS-серверы, которые нужно прописать у регистратора домена: без делегирования зону не видит никто, какими бы правильными ни были записи в ней. Зона создаётся под регистрируемым именем — последние две метки.
- Ответ маршрута говорит, видит ли провайдер делегирование (`delegated`), создавалась ли зона (`zone_created`) и какие NS-серверы нужны (`nameservers`).
- Шаг «Домен» стоит первым и необязателен: без домена сервис доступен по адресу сервера. Переменные `SETUP_DOMAIN` и `BUNNY_API_KEY` пишет сама панель; ключ провайдера используется только для записи и проверки и обратно не показывается.
- Панель первого запуска теперь открывается в браузере по адресу сервера — порт API публикуется на время установки одной переменной и возвращается на loopback после неё (ADR-0025). Маршруты `/v1` не изменились.

## 2026-09-12, установщик записывает конфигурацию сам

- Страница первого запуска больше не печатает блок переменных для вставки руками: она **записывает** файл окружения на сервере — `POST /setup/env`. Значения проверяются теми же разборщиками, которыми сервис читает конфигурацию при старте, поэтому записанный файл — это файл, с которым сервис запускается. Маршруты `/v1` не изменились.
- `POST /setup/signer-values` и `GET /setup/signer-env` — выбор владельца для сервера подписи и **готовый файл окружения** для него вместе с командами по порядку. Пароль роли базы и два значения сида в него не попадают: первый уже есть на этом сервере, вторые создаются на том.
- Шаги «Сеть и узлы» и «Файл окружения» — новые и обязательные. Второй закрывается только когда значения не просто записаны, но и применены: переменные читаются один раз, при старте.
- Секрет, принятый страницей, обратно не отдаётся: в ответе `GET /setup/state` у него только признак «задано». Пустое поле означает «не менять».
- Поле, в которое вставили 12 или 24 коротких слова, отвергается: мнемоника не вводится на этой странице ни в одно поле. Обоснование и границы — в ADR-0024.

## 2026-09-12, страница первого запуска

- Пока настройка сервиса не завершена, API отдаёт страницу `GET /setup`, которая ведёт по шагам и проверяет каждый. Когда все обязательные шаги закрыты, её маршруты отвечают `404`. Мерчантов это не касается: маршруты `/v1` не изменились.
- Служебные маршруты страницы: `GET /setup/state`, `POST /setup/verify`, `POST /setup/steps/{key}`, `POST /setup/merchant`. Доступны только из приватной сети и только с одноразовым кодом из лога сервиса. См. первый запуск.
- Страница не принимает и не создаёт мнемонику, парольную фразу и приватную половину операторского ключа — обоснование в ADR-0024.

## 2026-09-12, отправка выплат

- События `payout.confirmed` и `payout.failed`: выплата подтверждена сетью или её транзакция попала в блок неуспешной. Поля — в [вебхуках](https://stons.io/ru/docs/webhooks.md#события). Как и раньше, тело вебхука — сигнал «сходи проверь»: состояние выплаты берите из `GET /v1/payouts/{id}`.
- Выплата в `failed` не повторяется автоматически: новая попытка требует нового `reference`.
- Остальное в этом обновлении внутреннее: подпись выплат с горячего кошелька, вторая независимая проверка вайтлиста вместе с подписью оператора, предохранитель, останавливающий выплаты сам. Публичные маршруты не изменились.

## 2026-09-12, выплаты

- `POST /v1/payouts` — создание выплаты, идемпотентное по `reference`. Ответ `202` у созданной выплаты, `200` у повтора. См. [выплаты](https://stons.io/ru/docs/payouts.md).
- `GET /v1/payouts/{id}` — текущее состояние выплаты с её статусом и причинами ожидания.
- Выплата возможна только на адрес из вайтлиста мерчанта и только после задержки перед первым использованием. Переход лимита выплату не отклоняет: она принимается со статусом `pending_review` и ждёт подтверждения человека, а `review_reasons` называет перейденные пределы. См. [лимиты](https://stons.io/ru/docs/payouts.md#лимиты).
- Новые коды ошибок: `payout_not_found`, `reference_conflict`, `asset_not_payable`, `address_not_whitelisted`, `payouts_halted`. См. [коды ошибок](https://stons.io/ru/docs/errors.md).
- Отправка выплат в сеть и события вебхуков `payout.confirmed` и `payout.failed` появятся в следующем обновлении: пока выплата доходит до статуса `queued` и ждёт исполнения.

## 2026-09-12, свипы

- Инвойс доходит до статуса `settled`: средства по нему перенесены в холодное хранилище. Для мерчанта это то же, что `confirmed`, вебхука у перехода нет — товар отдаётся на `confirmed`, как и раньше. См. [статусы](https://stons.io/ru/docs/invoices.md#статусы).
- Остальное в этом обновлении внутреннее: подпись и отправка свипов, подтверждение их в цепи и проводки в реестре. Публичные маршруты и события вебхуков не изменились.

## 2026-09-11, операционные маршруты

- `GET /admin/health` — состояние сервиса для оператора и мониторинга: отставание сканера в блоках и глубина очереди вебхуков. См. операционное состояние.
- `GET /metrics` — те же показатели в текстовом формате Prometheus.
- Оба маршрута служебные: аутентификации не требуют, данных мерчантов не содержат и доступны только в приватной сети.

## 2026-09-11, доставка вебхуков

- События из очереди уходят на URL мерчанта с подписью `X-Signature` и заголовком `X-Timestamp`, с повторами по расписанию из [описания вебхуков](https://stons.io/ru/docs/webhooks.md#доставка). До этого события только записывались.
- Заголовок `User-Agent` исходящих вебхуков содержит название продукта.
- Ответ `3xx` не считается успешной доставкой и не выполняется.

## 2026-09-11, сканер платежей

- Инвойсы меняют статус по переводам в сети: `seen`, `confirmed`, `underpaid`, `expired`, `paid_late`. См. [статусы](https://stons.io/ru/docs/invoices.md#статусы).
- В ответе `GET /v1/invoices/{id}` поле `deposits` заполняется платежами по инвойсу.
- Сервис формирует события вебхуков `invoice.seen`, `invoice.confirmed`, `invoice.overpaid`, `invoice.underpaid`, `invoice.expired`, `invoice.paid_late`, `deposit.confirmed` и `deposit.orphaned`. См. [события](https://stons.io/ru/docs/webhooks.md#события). Отправка событий на URL мерчанта включится в следующем обновлении.

## 2026-09-11, адреса и инвойсы

- Аутентификация по заголовку `X-Api-Key` и лимиты запросов по ключу и по IP-адресу — см. [аутентификацию](https://stons.io/ru/docs/authentication.md).
- `POST /v1/addresses` — постоянный адрес пользователя для мерчантов в режиме `per_user`. См. [адреса](https://stons.io/ru/docs/addresses.md).
- `POST /v1/invoices` — создание инвойса, идемпотентное по `order_id`. См. [инвойсы](https://stons.io/ru/docs/invoices.md).
- `GET /v1/invoices/{id}` — текущее состояние инвойса с его платежами.
- `GET /v1/openapi.json` — машиночитаемое описание API в формате OpenAPI 3.1.
- Новые коды ошибок: `validation_failed`, `unauthorized`, `merchant_disabled`, `invoice_not_found`, `address_mode_mismatch`, `order_id_conflict`, `asset_not_supported`, `amount_below_minimum`, `rate_limited`, `addresses_exhausted`. См. [коды ошибок](https://stons.io/ru/docs/errors.md).

## 2026-09-11, служебные маршруты

- Добавлены служебные маршруты `GET /healthz` и `GET /readyz` — см. мониторинг.
- Введён единый формат ошибок `{ "error": { "code", "message" } }` и коды `bad_request`, `route_not_found`, `internal_error`, `service_unavailable` — см. [коды ошибок](https://stons.io/ru/docs/errors.md).
- Каждый ответ содержит заголовок `X-Request-Id` для поиска запроса в логах.