Инвойсы

Этот документ описывает инвойсы: как создать инвойс через POST /v1/invoices, получить его состояние через GET /v1/invoices/{id} и понимать его статусы, суммы и комиссии. Прочитайте его до приёма первого платежа.

Инвойс — ожидание платежа на конкретную сумму в конкретном активе до дедлайна. Мерчант (в кабинете — проект) создаёт инвойс под заказ и либо сам показывает покупателю сумму и адрес, либо отправляет покупателя на страницу оплаты. Покупатель — тот, кто платит. Все времена в запросах и ответах — ISO 8601 в UTC, например 2026-09-11T21:03:05.531Z.

Активы

Что сервис принимает. Адреса контрактов прочитаны в сети, а не взяты из статей. Какие из этих активов доступны вашему проекту прямо сейчас, говорит GET /v1/assets: оператор может выключить актив или сеть, например на обслуживание, и тогда их в ответе не будет.

Активы TRON

USDC_TRON выключен оператором целиком: Circle прекратила выпуск USDC в сети TRON. Инвойс в USDC_TRON и инвойс с USDC_TRON в currencies отклоняются с 422 asset_payments_disabled; страница оплаты его не предлагает, в assets постоянного адреса его нет; выплата в нём отклоняется с 422 asset_payouts_disabled. Уже открытые инвойсы в нём оплачиваются, а перевод USDC на постоянный адрес per_user зачисляется, как раньше, — см. что приходит на адрес.

Активы EVM-сетей

• Выплат в EVM-сетях нет: выплата в любом из этих активов отклоняется с 422 asset_not_payable.
• USDT в Polygon, Arbitrum и OP Mainnet — это USDT0, отдельный контракт с собственным идентификатором актива. Для покупателя это тот же USDT, для вашего кода — другой asset.
• Знаки после запятой разные: у USDT и USDC в BNB Smart Chain их 18, в остальных сетях — 6. Не вшивайте это число в код.
• Число подтверждений — глубина, на которой сервис считает платёж окончательным в этой сети. Оно разное: от 1 в Avalanche до 4800 в Arbitrum, где блоки идут примерно каждые 0,25 секунды.

Активы TON

Контракт — мастер-контракт жетона в raw-форме, в которой его хранит каталог; тот же контракт в user-friendly форме — EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs:

Платежу в TON нужно одно подтверждение: блок мастерчейна TON выходит примерно раз в 0,4 секунды, а сервис считает только транзакции, которые сеть сделала окончательными, поэтому платёж подтверждается за секунды. Адрес инвойса в TON — в user-friendly форме, см. адреса в TON.

Активы Solana

Контракт — mint токена, в base58 и регистрозависимо. Оба mint принадлежат классической токен-программе SPL TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA:

• Выплат в Solana нет: выплата в любом из этих активов отклоняется с 422 asset_not_payable.
• Платежу в Solana нужно одно подтверждение: сервис считает только то, что сеть сделала окончательным на настроенном оператором уровне подтверждения. По умолчанию это finalized — единственный уровень, который не откатывается.
• У Solana нет chain id. Сеть этого семейства различается по genesis-хэшу, а не по номеру. Идентификаторы, которые видит ваш код, — это id сетей из реестра: solana для боевой сети.
• Адрес и подпись транзакции в Solana — base58 и регистрозависимы. Подпись, которую сервис возвращает в tx_hash, — это 86–88 знаков base58, а не 64 шестнадцатеричных знака. Никогда не приводите ни адрес, ни подпись к нижнему регистру — см. адреса в Solana.
• Токен в Solana лежит не на адресе владельца, а в его associated token account — отдельном аккаунте на пару (владелец, mint). Этот аккаунт сервис создаёт сам при выдаче адреса, поэтому кошелёк покупателя платит на адрес как обычно и знать о нём ничего не должен.

Нативные монеты

TRX_TRON, GRAM_TON, SOL_SOLANA и нативные монеты EVM-сетей оплачивают инвойсы наравне с токенами: цена в долларах США переводится в монету по курсу, как у любого актива с курсом, — см. цену и курс. Выплат в них нет: выплата отклоняется с 422 asset_not_payable.

Нативная монета EVM-сети засчитывается, отправил её кошелёк или смарт-контракт — суммой самой транзакции или переводом, который сделал внутри неё смарт-контракт (смарт-кошелёк, мультиподпись, вывод с биржи). Перевод из контракта сервис находит трейсом блока и засчитывает, только если трейс объясняет весь рост баланса адреса; перевод, который объяснить не удалось, автоматически не засчитывается: инвойс остаётся неоплаченным, вебхука нет, и его разбирает оператор вручную. Токен засчитывается по событию перевода, как бы его ни отправили.

Перевод монеты на адрес инвойса в другом активе записывается как unexpected_asset: мерчанту он не зачисляется и инвойс не закрывает — см. что приходит на адрес.

Тестовые сети

Установка в тестовой сети TRON (Nile или Shasta) принимает только USDT_TRON — с контрактом этой сети. Её сеть TON — TON testnet, и в ней только GRAM_TON: USDT выпущен только в боевой сети TON. Её сеть Solana — solanadevnet, Solana devnet, и в ней только USDC и нативная монета; идентификаторы активов и mint там свои — USDC в devnet — это 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU.

Правила, которые следуют из таблиц:

• Перевод меньше минимального депозита своего актива — пыль: сервис его записывает, но мерчанту не зачисляет и ни в один инвойс не засчитывает. Исключение — остаток инвойса per_invoice: если по инвойсу уже пришёл платёж, а сумма ещё не набрана, перевод в активе инвойса на его адрес — платёж любой ненулевой суммы, см. частичная оплата.
• Инвойс с ценой в долларах США (созданный без asset) оплачивается любым активом, который проект принимает и для которого у сервиса есть курс; currencies сужает этот список. Какие это активы в данный момент, говорит GET /v1/assets.
• Число знаков, минимальные депозиты и число подтверждений берутся из каталога активов сервиса. В коде ни одно из этих чисел не зашито.

Суммы

Суммы передаются строками в единицах актива, например "49.900000". JSON-числа для сумм не используются: при разборе в число с плавающей точкой копейки теряются.

• В запросе сумма — цифры с необязательной дробной частью через точку: 49, 49.9, 49.90, 0.5. Сумма отклоняется с 400 validation_failed, если в ней есть знак, экспонента, пробел, запятая, ведущий ноль (049), точка без цифр с обеих сторон (49., .9) или больше знаков после точки, чем у актива.
• В ответе у каждой суммы в активе ровно столько знаков после точки, сколько у актива: "49.900000" для актива с 6 знаками. У цены в долларах США (price.amount) — всегда 6.
• Число знаков. Не зашивайте число 6 в код: считайте знаки после точки в amount_expected — там всегда все знаки актива инвойса.
• Сравнение. Сравнивайте суммы как десятичные числа, а не как строки: "49.9" в запросе и "49.900000" в ответе — одна и та же сумма.

Список активов

GET /v1/assets возвращает активы, в которых мерчант может выставить инвойс в момент запроса, с сетью, контрактом, числом знаков и минимальным депозитом каждого. По нему решают, какие токены предложить, вместо того чтобы зашивать список в код.

Запрос

У запроса нет параметров и тела. В ответе есть ETag, поэтому продукт, который держит свой список монет свежим, платит за один 304, пока каталог не менялся, — см. условные чтения.

Ответ

200 с массивом assets в порядке сетей, который задал оператор, затем по идентификатору. Актив попадает в список, если выполнено всё:

• сервис принимает его для платежей, и оператор не выключил приём в нём;
• его не выключили настройки проекта;
• его сеть включена, и сервис сейчас выдаёт в ней адреса.

• Список говорит, что можно предложить сейчас, а не что зачисляется: перевод в активе, выпавшем из списка, обрабатывается по правилам своего адреса — см. что приходит на адрес.
• Список не зависит от проверки мерчанта и от приостановленного режима адресов: они отклоняют сам POST /v1/invoices своими кодами.

Ошибки

Пример

curl -s https://api.stons.io/v1/assets \
  -H "X-Api-Key: $API_KEY"

200 в mainnet TRON:

{
  "assets": [
    {
      "asset": "USDT_TRON",
      "symbol": "USDT",
      "network": "tron",
      "network_name": "TRON",
      "token_standard": "TRC-20",
      "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "decimals": 6,
      "min_amount": "1.000000",
      "confirmations": 20,
      "icon": "usdt"
    }
  ]
}

Создать инвойс

POST /v1/invoices создаёт инвойс под заказ или возвращает инвойс, который уже есть для того же order_id, — см. идемпотентность.

Запрос

Тело — JSON-объект с Content-Type: application/json, не больше 16 КиБ. Поле, которого нет в таблице, отклоняется с 400 validation_failed.

У запроса есть один параметр строки запроса — include, с единственным значением qr: тогда в ответе есть QR-код адреса. Любой другой параметр и любое другое значение отклоняются с 400 validation_failed.

Необязательное поле без значения не передаётся: null отклоняется с 400 validation_failed.

Ответ

201 — инвойс создан, 200 — инвойс для этого order_id уже был создан раньше. Тело в обоих случаях одинаковое. Все поля присутствуют всегда; поле, которое не применимо, равно null.

Идемпотентность

order_id — ключ идемпотентности. Когда приходит запрос с order_id, для которого инвойс уже есть, сервис сравнивает запрос с этим инвойсом:

• Тот же запрос получает 200 и текущее состояние инвойса. Запрос тот же, если совпадает всё перечисленное:
  • у инвойса, созданного с asset: тот же asset и тот же amount как число — он сравнивается с amount_requested, а не с amount_expected;
  • у инвойса, созданного без asset: нет asset, та же цена как число — она сравнивается с price.amount — и тот же набор currencies без учёта порядка и повторов. Так же и после того, как покупатель выбрал токен;
  • в обоих случаях те же external_user_id, return_url и cancel_url; отсутствующее поле совпадает только с отсутствующим.
• Любое отличие получает 409 order_id_conflict: это другой платёж. Запрос с asset для инвойса, созданного без него, и наоборот — тоже отличие.
• expires_in не сравнивается. Повтор с другим значением получает инвойс с прежним expires_at.

Одновременные запросы с одним order_id создают один инвойс; остальные получают 200 или 409 по тому же сравнению. Ответ на повтор показывает условия, записанные при создании инвойса, даже если ставка комиссии или настройки мерчанта с тех пор изменились.

Часть проверок выполняется до поиска существующего инвойса, поэтому повтор, который их не проходит, получает ошибку, а не инвойс:

• формат запроса, включая границы expires_in (400 validation_failed);
• external_user_id в режиме per_user (400 validation_failed);
• с asset: актив принимается к оплате (422 asset_not_supported), формат и число знаков суммы (400 validation_failed), минимальный депозит (422 amount_below_minimum);
• без asset: формат цены и то, что она больше нуля (400 validation_failed).

Все остальные проверки выполняются, только когда инвойса для order_id ещё нет, поэтому повтор уже созданного инвойса они не отклоняют. Это проверки: одобрение мерчанта, пауза режима адресов платформой, выключатели актива у оператора и у мерчанта, проверки currencies и курсов, адреса возврата и настройки комиссий.

Ошибки

Что делать клиенту при каждом коде — см. коды ошибок.

Пример

curl -s -X POST https://api.stons.io/v1/invoices \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_1001", "asset": "USDT_TRON", "amount": "49.9", "expires_in": 3600}'

201:

{
  "invoice_id": "6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "order_id": "ord_1001",
  "status": "created",
  "asset": "USDT_TRON",
  "network": "tron",
  "network_name": "TRON",
  "address": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "address_explorer_url": "https://tronscan.org/#/address/TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "payment_uri": null,
  "price": null,
  "currencies": null,
  "asset_selected_at": null,
  "quote": null,
  "amount_requested": "49.900000",
  "amount_expected": "49.900000",
  "amount_received": "0.000000",
  "amount_remaining": "49.900000",
  "amount_credited": "0.000000",
  "fees": {
    "service": { "payer": "merchant", "percent": "1.00", "fixed": "0.000000", "amount": "0.000000" },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "external_user_id": null,
  "return_url": null,
  "cancel_url": null,
  "checkout_url": "https://pay.example.com/pay/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "expires_at": "2026-09-11T21:03:05.531Z",
  "created_at": "2026-09-11T20:03:05.531Z",
  "deposits": []
}

Цена в долларах в выбранной монете

Самый короткий путь, если вы держите цены в долларах и уже знаете, в чём хотите получить деньги: один запрос, и в ответе всё для оплаты. Курс и пересчёт делает сервис.

curl -s -X POST https://api.stons.io/v1/invoices \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_2001", "asset": "SOL_SOLANA", "amount": "99", "price_currency": "USD", "expires_in": 3600}'

price_currency: "USD" означает, что amount — цена в долларах, а не количество монет. Поле необязательное: без него amount по-прежнему сумма в единицах актива, и ничего в вашей интеграции не меняется.

В ответе сразу то, что нужно показать покупателю:

• address — адрес, на который платить;
• amount_expected — сколько монет отправить;
• price — цена в долларах, как вы её прислали;
• quote.rate — курс, по которому посчитана сумма, и quote.expires_at — до какого момента она держится;
• expires_at — дедлайн инвойса; qr — при include=qr.

Страница оплаты такому инвойсу не нужна: монету выбрали вы.

Что с курсом дальше

Сумма зафиксирована котировкой. В токене, привязанном к доллару США, например USDT_TRON, она действует до дедлайна инвойса и не пересчитывается. В любом другом токене, когда окно котировки истекает, а инвойс всё ещё ждёт денег, сервис пересчитывает остаток по новому курсу: уже полученное остаётся полученным, а недоплата считается в долларах по курсу инвойса. Подробности — в окне котировки.

Если курса нет или он устарел, инвойс не создаётся: ответ 503 rate_unavailable, и в базе ничего не остаётся. Лучше честный отказ, чем инвойс без адреса и суммы.

Повтор с тем же order_id возвращает тот же инвойс с той же суммой — как и для любого другого инвойса.

Показать «≈ 0,45 SOL» до создания

GET /v1/rates отдаёт по каждому активу проекта курс, по которому и будет посчитан инвойс: рыночный с уже снятой наценкой сервиса. Поэтому число, которое вы покажете покупателю заранее, совпадёт с тем, что встанет в инвойс.

curl -s https://api.stons.io/v1/rates -H "X-Api-Key: $API_KEY"

{
  "rates": [
    {
      "asset": "SOL_SOLANA",
      "symbol": "SOL",
      "rate": "213.450000000000000000",
      "market_rate": "220.050000000000000000",
      "markdown_percent": "3.00",
      "observed_at": "2026-10-06T12:31:07.218Z",
      "fresh": true,
      "currency": "USD"
    }
  ]
}

Лента изменений

GET /v1/invoices отдаёт инвойсы проекта в том порядке, в каком менялось их состояние, от самого старого изменения к новому. Это догон: вебхук приходит за секунды и остаётся основным путём, а лента нужна, когда приёмник лежал дольше, чем покрывают семь доставок.

Запрос

Любой другой параметр строки запроса отклоняется с 400 validation_failed; include — в их числе, поэтому в ленте никогда нет QR-кодов. В ответе есть ETag: проход, который не нашёл нового, стоит одного 304 без тела — см. условные чтения.

Ответ

Переводы в ленту не кладутся намеренно: страница из пятидесяти инвойсов несла бы сотни строк, о которых не просили, а сколько пришло, видно по суммам самого инвойса. Нужны переводы — возьмите инвойс по идентификатору.

Страница заканчивается на последней строке, и следующая начинается строго после неё. Поэтому инвойс, изменившийся во время обхода, не сдвигает страницу — в отличие от смещения, при котором строка может быть пропущена или прочитана дважды. Курсор, который сервис не выдавал, отклоняется с 400 validation_failed.

Как держать свои заказы в соответствии:

1. Обрабатывайте вебхуки — это быстрый путь.
2. Храните момент последнего обработанного изменения.
3. Если вебхуки не приходили, пройдите ленту с этого момента, страница за страницей, пока next_cursor не станет null, и сдвиньте момент.

Токен выбирает покупатель

Запрос без asset создаёт инвойс без токена: покупатель выбирает монету и сеть на странице оплаты и видит сумму и адрес только после выбора.

• Цена. amount — цена в долларах США. При выборе сервис переводит её в выбранный токен по курсу — см. цену и курс.
• Страница оплаты. Она обязательна. Если в установке её нет, запрос отклоняется с 422 asset_required.
• Разрешённые токены с currencies. При создании каждый актив из списка должен приниматься к оплате (422 asset_not_supported), быть включён оператором (422 asset_payments_disabled) и в настройках проекта (422 asset_disabled_by_merchant) и иметь курс (422 asset_not_offered). Цена, переведённая по текущему курсу, должна быть не меньше его минимального депозита (422 amount_below_minimum).
• Разрешённые токены без currencies. При создании сервис берёт все активы, которые принимаются к оплате, включены оператором и в настройках проекта и имеют курс. Если таких нет — 422 no_payable_assets. Каждый взятый актив должен принимать цену, переведённую по текущему курсу, не меньше минимального депозита — с той же ошибкой, что выше.
• Свежего курса при создании нет. Разрешённый актив, курс которого в этот момент не свежий, с минимальным депозитом не сверяется: его проверит страница оплаты, когда будет предлагать выбор. Если свежего курса нет ни у одного разрешённого актива, запрос отклоняется с 503 rate_unavailable, и инвойс не создаётся: оплатить его сейчас никто не смог бы.
• Что предлагает страница. Из разрешённых токенов страница оплаты предлагает те, что проходят те же проверки в момент показа страницы, каждый с суммой по текущему курсу.
• До выбора asset, network, address, quote, amount_requested, amount_expected, amount_received, amount_remaining, amount_credited, fees.service.fixed и fees.service.amount равны null, а в price — цена. Ставка комиссии и плательщики записываются при создании, как у любого инвойса.
• Выбор возможен, пока статус created и часы сервиса не дошли до expires_at. Выбор окончательный: сменить токен нельзя. При выборе сервис записывает актив, выдаёт адрес, переводит цену в токен и записывает первую котировку. amount_expected он считает от переведённой цены так же, как у инвойса, созданного в этом активе: со ставкой и плательщиками, записанными при создании, и фиксированной частью комиссии этого актива на момент выбора. asset_selected_at — момент выбора. Дальше инвойс оплачивается как инвойс, созданный с этим активом, с одним отличием: после окна котировки остаток долга пересчитывается.
• Выбора не было до дедлайна. Когда часы сервиса доходят до expires_at, инвойс становится expired, и приходит invoice.expired с asset и суммами, равными null. Оплатить такой инвойс нельзя: адреса у него нет.
• Режим per_user. external_user_id обязателен, как всегда, а после выбора инвойс получает постоянный адрес пользователя. Перевод на этот адрес, попавший в блок до выбора, инвойс не оплачивает: это пополнение, оно зачисляется на баланс мерчанта с комиссией пополнения, и приходит deposit.confirmed с invoice_id, равным null. Страница оплаты показывает адрес только после выбора, поэтому не давайте покупателю постоянный адрес для оплаты такого инвойса в обход страницы.

curl -s -X POST https://api.stons.io/v1/invoices \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_1002", "amount": "49.9", "currencies": ["USDT_TRON"]}'

201:

{
  "invoice_id": "8d2c7a4e-1b3f-4c5d-9e6f-7a8b9c0d1e2f",
  "order_id": "ord_1002",
  "status": "created",
  "asset": null,
  "network": null,
  "network_name": null,
  "address": null,
  "address_explorer_url": null,
  "payment_uri": null,
  "price": { "amount": "49.900000", "currency": "USD" },
  "currencies": ["USDT_TRON"],
  "asset_selected_at": null,
  "quote": null,
  "amount_requested": null,
  "amount_expected": null,
  "amount_received": null,
  "amount_remaining": null,
  "amount_credited": null,
  "fees": {
    "service": { "payer": "merchant", "percent": "1.00", "fixed": null, "amount": null },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "external_user_id": null,
  "return_url": null,
  "cancel_url": null,
  "checkout_url": "https://pay.example.com/pay/8d2c7a4e-1b3f-4c5d-9e6f-7a8b9c0d1e2f",
  "expires_at": "2026-09-11T21:03:05.531Z",
  "created_at": "2026-09-11T20:03:05.531Z",
  "deposits": []
}

Цена и курс

Цену в долларах США сервис переводит в токен по курсу — цене одной целой монеты токена в долларах США. Курсы сервис собирает сам из источника рыночных данных и считает по курсу, только пока тот свежий.

• Стейблкоины тоже. Токен, привязанный к доллару США, переводится по своему рыночному курсу, а не один к одному: при 0.9991 USD за USDT цена 100 USD — это 100.090082 USDT.
• Токен, не привязанный к доллару США, переводится по рыночному курсу, пониженному на наценку платформы, поэтому монет покупатель отправляет больше. У токена, привязанного к доллару США, наценки нет.
• Округление вверх. Сумма округляется вверх до шага токена, поэтому покупатель платит не меньше цены. Шаг зависит от того, к чему токен привязан. У токена, привязанного к доллару, шаг — его цент: цена $229.00 при курсе 0.9999 просит 229.03, а не 229.024488. У токена, не привязанного ни к чему, шаг — 0.00000001 его единицы: цент эфира стоил бы 26 долларов, и округлять до него нельзя. Шаг никогда не мельче минимальной единицы самого токена.
• Любая цена с не больше чем 6 знаками переводится: отказа из-за того, что цена не записывается в токене точно, нет.
• По какому курсу. По курсу, который страница оплаты показала покупателю, если при выборе он ещё свежий; иначе — по последнему свежему. Сумма, записанная при выборе, — ровно та, что была показана, пока показанный курс свежий.
• Комиссия сервиса считается от переведённой цены, как у инвойса, созданного в этом токене, — см. комиссии.
• Свою цену сверяйте с price.amount. amount_requested такого инвойса — цена, переведённая в токен.

Котировка

quote описывает курс, по которому посчитаны текущие суммы в токене:

quote равен null у инвойса, созданного с asset, до выбора и у инвойса, токен которого выбран до появления курсов: такой инвойс переведён один к одному и не пересчитывается.

quote сразу после выбора USDT_TRON по курсу 0.9991 USD за USDT; expires_at — дедлайн инвойса, потому что токен привязан к доллару:

{
  "rate": "0.999100000000000000",
  "market_rate": "0.999100000000000000",
  "markdown_percent": "0.00",
  "currency": "USD",
  "number": 1,
  "expires_at": "2026-09-11T21:03:05.531Z"
}

Окно котировки

Суммы котировки действуют до quote.expires_at.

• Токен, привязанный к доллару США (USDT_*, USDC_*): quote.expires_at равен expires_at инвойса. Сумма, зафиксированная при выборе, действует всю жизнь инвойса, и остаток после частичной оплаты тоже: курс такого токена отходит от доллара на сотые доли процента, допуска недоплаты нет, и сумма, сдвинувшаяся под покупателем, оставила бы того, кто заплатил ровно показанное, без нескольких центов. Курс при выборе всё равно читается, один к одному его не берут.
• Любой другой токен: окно задаёт платформа, оно отсчитывается от момента котировки и никогда не заканчивается позже expires_at инвойса.
• После окна токена, не привязанного к доллару, сервис пересчитывает остаток долга по текущему курсу, если инвойс в статусе created или partially_paid, его дедлайн не прошёл и ни один перевод на него не ждёт подтверждений. Окно считается по времени блоков: сервис пересчитывает, только когда обработал блоки позже конца окна, поэтому каждый перевод, отправленный в окне, уже учтён.
• Что меняется. Остаток долга стоит в долларах США столько, сколько стоил по старому курсу; новая котировка просит эту стоимость по новому курсу, с тем же округлением вверх. amount_expected становится равным amount_received плюс новый остаток, и amount_remaining следует за ним. amount_requested меняется на ту же величину: часть amount_expected, которая была комиссией сервиса на покупателе, сохраняет своё число единиц токена. У quote — следующий number, новые курсы и новый expires_at.
• Что не меняется. Цена в price, статус, адрес, ставка комиссии и плательщики. Вебхук не отправляется: текущие суммы читайте запросом GET /v1/invoices/{id}. Страница оплаты показывает их сама.
• Платёж прежней суммы. Покупатель мог скопировать сумму, пока действовала прежняя котировка, а перевод — попасть в блок уже после того, как её сменила новая. Перевод в блоке не позже 10 минут после конца окна прежней котировки оценивается и по её сумме: если платежи к этому моменту её покрыли, инвойс становится confirmed, и его amount_requested, amount_expected и quote снова те, что у прежней котировки. Перевод позже оценивается только по действующей котировке. Зачисляется всегда то, что пришло.
• Свежего курса нет. Старые суммы действуют, пока свежий курс не появится; сервис пробует снова на следующем проходе.
• Инвойс, созданный с asset, не пересчитывается никогда: его сумму мерчант задал в токене.

Получить инвойс

GET /v1/invoices/{id} возвращает текущее состояние инвойса. Решение, отдавать ли товар, принимайте по этому ответу — после вебхука, после редиректа со страницы оплаты и при опросе, — а не по телу вебхука: см. вебхуки.

Запрос

Чтение условное: в ответе есть ETag, и запрос, который вернул его в If-None-Match, получает 304 Not Modified без тела, пока ничего не изменилось, — см. условные чтения.

Ответ

200 с тем же объектом, что в ответе на создание, — см. создать инвойс. Поля элемента deposits:

В deposits — только платежи по этому инвойсу, в порядке их блоков. Пыли, переводов другого актива, переводов, исчезнувших при реорганизации цепи, и пополнений per_user там нет.

Ошибки

Мерчант, который ещё не одобрен, читать свои инвойсы может: этот маршрут merchant_not_approved не возвращает.

Пример

curl -s https://api.stons.io/v1/invoices/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44 -H "X-Api-Key: $API_KEY"

200 — инвойс из примера создания после оплаты:

{
  "invoice_id": "6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "order_id": "ord_1001",
  "status": "confirmed",
  "asset": "USDT_TRON",
  "network": "tron",
  "network_name": "TRON",
  "address": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "address_explorer_url": "https://tronscan.org/#/address/TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "payment_uri": null,
  "price": null,
  "currencies": null,
  "asset_selected_at": null,
  "quote": null,
  "amount_requested": "49.900000",
  "amount_expected": "49.900000",
  "amount_received": "49.900000",
  "amount_remaining": "0.000000",
  "amount_credited": "49.401000",
  "fees": {
    "service": { "payer": "merchant", "percent": "1.00", "fixed": "0.000000", "amount": "0.499000" },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "external_user_id": null,
  "return_url": null,
  "cancel_url": null,
  "checkout_url": "https://pay.example.com/pay/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "expires_at": "2026-09-11T21:03:05.531Z",
  "created_at": "2026-09-11T20:03:05.531Z",
  "deposits": [
    {
      "tx_hash": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c",
      "amount": "49.900000",
      "confirmations": 20,
      "status": "confirmed",
      "block_time": "2026-09-11T20:10:42.000Z",
      "late": false,
      "explorer_url": "https://tronscan.org/#/transaction/50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"
    }
  ]
}

Куда уходят деньги

Подтверждённый платёж ждёт на адресе приёма, пока сервис его не перенесёт. Куда переносить — свойство проекта, которое задаёт оператор, и для API оно не меняет ничего: те же запросы, те же статусы, те же вебхуки.

• По умолчанию деньги уходят в хранилище сервиса, а баланс мерчанта — это то, что сервис ему должен: читается через баланс и выводится в кабинете.
• Проекту, которому оператор включил прямые сборы, деньги каждого платежа пересылаются на его собственный кошелёк за вычетом комиссии сервиса, без всяких запросов. Баланс у такого проекта поэтому остаётся нулевым: ноль здесь значит, что деньги уже на его кошельке, а не что ему не платили.

Что из этого следует для интеграции:

• settled значит «деньги ушли с адреса приёма». Для проекта с прямыми сборами это его собственный кошелёк, для всех остальных — хранилище. Товар в обоих случаях отдаётся на confirmed, ждать settled не нужно никогда.
• Мелкие платежи копятся. Сервис переносит деньги, только когда перевод стоит своих затрат, а это порог по активу: ниже порога платёж ждёт на адресе приёма, пока следующие платежи на тот же адрес не наберут сумму или пока его не перенесёт сотрудник руками. В TRON перевод стоит около доллара, поэтому порог там — десятки долларов; в EVM-сетях и TON — центы. Инвойс при этом всё равно confirmed, а amount_received говорит правду о том, что пришло.
• Заявка на вывод по-прежнему работает для того, что проект заработал до переключения. Деньги, уже едущие на собственный кошелёк проекта, к выводу не предлагаются: это были бы одни деньги дважды.

QR-код

Продукт, который рисует свою страницу оплаты, просит QR-код адреса параметром include=qr — при создании и при чтении одного инвойса:

curl -s "https://api.stons.io/v1/invoices/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44?include=qr" -H "X-Api-Key: $API_KEY"

У инвойса появляется одно поле — qr — с кодом в виде SVG-картинки в data:-ссылке. Здесь она сокращена, целиком это около 11 КБ:

"qr": { "address": "data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgNDUgNDUi…" }

Показывайте её как src у <img>: ни библиотеки QR на вашей стороне, ни второго запроса.

<img src="data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgNDUgNDUi…" alt="" width="240" height="240">

• В коде лежит адрес оплаты address — целиком и в том виде, в каком его отдаёт инвойс. Это та же картинка, которую рисует страница оплаты, поэтому кошелёк читает ваш экран и наш одинаково.
• qr.address — null, пока покупатель не выбрал токен: у инвойса ещё нет адреса. Самого поля нет, если его не попросили через include=qr.
• include принимают только POST /v1/invoices и GET /v1/invoices/{id}. Лента изменений — нет: страница из пятидесяти кодов это полмегабайта, которых никто не просил.
• В коде нет payment_uri. Наша страница даёт эту ссылку кнопкой, а не кодом; рисуйте свой код по ней, если проверили, что кошельки ваших покупателей читают такие ссылки с камеры.
• Картинка — SVG, в котором ничего не исполняется, чёрное на белом, и масштабируется до любого размера. Задайте ей размер в своей разметке, а alt оставьте пустым: адрес стоит рядом текстом и целиком, и читать с экрана надо его, а не картинку.

Статусы

Статусы меняет сканер блокчейна. Он читает блоки с отставанием в один блок от головы цепи, поэтому перевод виден через несколько секунд. Подтверждение USDT в TRON — 20 блоков, около минуты. В TON — один блок, несколько секунд.

Термины ниже:

• Вовремя — перевод, у которого block_time не позже expires_at. С опозданием — перевод, у которого block_time позже.
• Дедлайн прошёл — сервис обработал блок со временем позже expires_at. Для инвойса, токен которого не выбран, — часы сервиса дошли до expires_at.

Переходы:

• created → seen: в блоке появился перевод вовремя.
• seen → confirmed: подтверждённые переводы вовремя достигли amount_expected.
• seen → partially_paid: до дедлайна последний неподтверждённый перевод вовремя подтвердился или исчез при реорганизации, а подтверждённых переводов вовремя меньше amount_expected.
• partially_paid → seen: до дедлайна в блоке появился ещё один перевод вовремя.
• seen → created: до дедлайна единственный перевод вовремя исчез при реорганизации цепи.
• created → expired: дедлайн прошёл без переводов вовремя.
• partially_paid → underpaid, partially_paid → paid_late: дедлайн прошёл, остаток вовремя не пришёл; новый статус следует из таблицы.
• seen → underpaid, seen → paid_late, seen → expired: дедлайн прошёл, и последний неподтверждённый перевод вовремя подтвердился или исчез; новый статус следует из таблицы.
• underpaid → paid_late, expired → paid_late: подтвердился перевод с опозданием.
• underpaid → seen, expired → seen: исчезнувший при реорганизации перевод вернулся в блок до дедлайна. Это редкий случай.
• confirmed → settled: средства ушли с адреса приёма — см. куда уходят деньги.

stateDiagram-v2
  [*] --> created
  created --> seen: перевод вовремя в блоке
  seen --> created: перевод исчез при реорганизации
  seen --> confirmed: подтверждённая сумма вовремя достигла ожидаемой
  seen --> partially_paid: до дедлайна подтверждена часть суммы
  partially_paid --> seen: ещё перевод вовремя в блоке
  partially_paid --> underpaid: дедлайн, остаток не пришёл
  partially_paid --> paid_late: дедлайн, подтверждён перевод с опозданием
  created --> expired: дедлайн без переводов
  seen --> underpaid: дедлайн, подтверждено меньше ожидаемого
  seen --> expired: дедлайн, перевод вовремя исчез
  seen --> paid_late: дедлайн, подтверждён перевод с опозданием
  underpaid --> paid_late: подтверждён перевод с опозданием
  expired --> paid_late: подтверждён перевод с опозданием
  underpaid --> seen: перевод вернулся в цепь
  expired --> seen: перевод вернулся в цепь
  confirmed --> settled: средства ушли с адреса

Правила:

• До дедлайна переводы на адрес инвойса суммируются: первый перевод не окончательный.
• Подтверждённый перевод остаётся в учёте. Исчезнуть при реорганизации может только неподтверждённый перевод; мерчант тогда получает deposit.orphaned.
• Перевод на инвойс в статусе confirmed, settled или paid_late статус не меняет: amount_received растёт, а deposit.confirmed сообщает о переводе.
• Дедлайн определяется по обработанным блокам, поэтому инвойс может оставаться created, seen или partially_paid несколько секунд после expires_at, а пока перевод вовремя ждёт подтверждений — и дольше.

О смене статуса мерчант получает вебхук, названный по новому статусу: invoice.seen, invoice.partially_paid, invoice.confirmed, invoice.underpaid, invoice.expired или invoice.paid_late. При переплате вместе с invoice.confirmed приходит ещё invoice.overpaid. У переходов в created и в settled вебхука нет. Событие приходит при каждом переходе: инвойс, который переходит из partially_paid в seen с новым переводом и обратно, когда этот перевод исчез, получает invoice.seen и invoice.partially_paid снова.

Частичная оплата

Допуска недоплаты нет: инвойс становится confirmed, только когда подтверждённые переводы вовремя покрыли весь amount_expected. Если покупатель прислал меньше, до дедлайна он может дослать остаток на тот же адрес.

• partially_paid — момент просить доплату. Покажите покупателю amount_remaining и тот же address и напомните про expires_at. Страница оплаты делает это сама — см. страницу оплаты.
• Остаток меньше минимального депозита актива тоже оплачивает инвойс. Пока по инвойсу уже пришёл платёж, а amount_expected ещё не набран, перевод в активе инвойса на его адрес — платёж, даже если он меньше min_amount, лишь бы больше нуля. Первый перевод по инвойсу и перевод после того, как сумма набрана, по-прежнему пыль, если они меньше минимального депозита.
• seen — перевод ждёт подтверждений, и amount_remaining его ещё не учитывает. Не просите доплату: остаток, возможно, уже в пути. После подтверждения инвойс станет confirmed или partially_paid с точным остатком.
• После дедлайна остаток уже не оплачивает инвойс. Перевод в блоке позже expires_at делает его paid_late, а без такого перевода инвойс становится underpaid. Что делать с заказом, решает мерчант.
• У инвойса, созданного без asset, в токене, не привязанном к доллару США, остаток может пересчитаться после окна котировки: берите amount_remaining из свежего ответа, а не из прежнего.
• Биржа может удержать комиссию за вывод из суммы, которую отправляет покупатель, и на адрес придёт меньше. Предупредите покупателя: на адрес должна прийти вся сумма.

amount_remaining считается как amount_expected минус amount_received, но не меньше нуля, поэтому у confirmed и settled он равен нулю. У underpaid и paid_late это недостача относительно amount_expected: переводы с опозданием в amount_received входят.

Режим per_user

В режиме per_user у пользователя мерчанта один постоянный адрес, и все инвойсы пользователя оплачиваются на него — см. адреса. Когда перевод на этот адрес появляется в блоке, сервис один раз решает, что он оплачивает:

• Инвойс, если у пользователя есть подходящий: тот же актив, amount_expected равен сумме перевода, статус created без других переводов, и expires_at не раньше времени блока перевода. Из нескольких таких инвойсов оплачивается созданный раньше всех.
• Пополнение в остальных случаях: перевод зачисляется на баланс мерчанта с комиссией пополнения, и приходит deposit.confirmed с invoice_id, равным null. Пополнение никогда не оплачивает инвойс позже.

Следствия:

• перевод на другую сумму — пополнение, а не частичная оплата;
• перевод на точную сумму после дедлайна — пополнение;
• инвойс, токен которого не выбран, в сопоставлении не участвует;
• сравнивается amount_expected: если комиссию сервиса платит покупатель, это цена вместе с комиссией;
• статусов partially_paid и underpaid в этом режиме не бывает, а paid_late бывает, только если реорганизация перенесла сопоставленный перевод в блок после дедлайна.

Комиссии

С каждого подтверждённого платежа STONS удерживает комиссию сервиса — процент и фиксированную сумму, которые назначает оператор. Процент — общий для платформы или свой у конкретного мерчанта; фиксированная сумма задаётся для каждого актива и одна для всех мерчантов. Любое из чисел может быть нулём. Кто платит комиссию сервиса — мерчант или покупатель, — задаёт настройка проекта «Кто платит комиссии» в кабинете.

Отдельной комиссии сети у инвойса нет. Затраты сети на приём — перенос средств с адреса приёма в хранилище — входят в комиссию сервиса. Это и говорит строка fees.network: status = included. Своя комиссия есть у выплат — см. комиссию за выплату.

Ставка и плательщики записываются в инвойс при его создании, а фиксированная сумма — когда становится известен актив: при создании у инвойса с asset, при выборе покупателя у инвойса без него. Записанные условия не меняются: смена тарифа или настроек проекта касается только новых инвойсов. Инвойсы, созданные до появления комиссии, записаны со ставкой 0, а созданные до появления фиксированной суммы — с фиксированной суммой 0.

Поля

Как считается комиссия сервиса

В формулах «ставка» — fees.service.percent, делённый на 100, «фиксированная» — fees.service.fixed, «получено» — сумма всех подтверждённых платежей инвойса.

• Покупатель платит комиссию. К цене прибавляются ставка от цены, округлённая вверх до последнего знака актива, и фиксированная сумма: amount_expected = amount_requested + ⌈amount_requested × ставка⌉ + фиксированная. Инвойс на 100 USDT при 2% и 1.70 USDT ждёт 103.70 USDT.
• Комиссия удерживается при подтверждении каждого платежа, в той же операции, что его зачисление, и считается от «получено»:
  • платит мерчант — min(получено, ⌊получено × ставка⌋ + фиксированная);
  • платит покупатель — min(получено, фиксированная + ⌊max(0, получено − фиксированная) × ставка / (1 + ставка)⌋): сначала фиксированная сумма, затем доля процента внутри оплаченного.
• Не больше полученного. Платёж меньше фиксированной суммы удерживается целиком, но не больше: зачисленное не уходит ниже нуля.
• Округление вниз, в пользу мерчанта. Каждый следующий перевод удерживает разницу между комиссией с новой суммы и уже удержанной, поэтому инвойс, оплаченный несколькими переводами, удерживает столько же, сколько оплаченный одним, а фиксированную сумму — один раз.
• Точная оплата покупателем удерживает ровно то, что прибавилось к цене, или на одну минимальную единицу актива меньше, если процент от цены не делится нацело: округление вниз оставляет эту единицу мерчанту.
• Переплата — комиссия с большей суммы. Недоплата — с полученного. Платёж после срока — как любой подтверждённый.
• Пыль и переводы другого актива комиссии не несут: это не платежи. Перевод, исчезнувший при реорганизации до подтверждения, не зачислен и комиссии не несёт.
• Пополнение per_user несёт комиссию с суммы перевода по ставке мерчанта и фиксированной сумме актива, действовавшим на время блока перевода, не больше суммы перевода; платит мерчант. Каждое пополнение — отдельная операция со своей фиксированной суммой. На баланс мерчанта поступает сумма перевода за вычетом этой комиссии; вебхуки deposit.* полей комиссий не несут.

Пример: цена 100 USDT, ставка 2%, фиксированная сумма 1.70 USDT, комиссию платит покупатель. Он платит двумя переводами: 1 USDT, затем 102.70 USDT.

Интеграция сравнивает свою цену с amount_requested у инвойса, созданного с asset, и с price.amount у инвойса, созданного без него: там amount_requested — цена, переведённая в токен. Покупателю показывается amount_expected: только эта сумма закрывает инвойс.