Инвойсы

Инвойс — ожидание платежа на конкретную сумму в конкретном активе до дедлайна. Мерчант создаёт инвойс под свой заказ, получает адрес и показывает его пользователю вместе с суммой.

Активы

Что сервис принимает в боевой сети TRON. Адреса контрактов прочитаны в сети, а не взяты из статей (ADR-0026):

TRX_TRON платежом пока не считается: перевод TRX на адрес приёма записывается как unexpected_asset и инвойс не закрывает. Причина и условие для изменения — в том же ADR. Выплаты в TRX не появятся и после: суточные лимиты складывают суммы в одной учётной единице, что верно только для привязанных к доллару активов.

В тестовых сетях принимается только USDT: проверяемого контракта USDC в Nile и Shasta нет — см. тестовые сети.

Единственный источник знаков, минимумов и числа подтверждений — таблица assets; в коде эти значения не зашиты нигде, поэтому добавление актива не меняет ни одной строки логики.

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

POST /v1/invoices

Запрос

Сумма должна быть не меньше минимального депозита актива: для USDT_TRON это 1 USDT. Переводы меньше минимального депозита сервис считает пылью и не зачисляет.

Ответ

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

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

Повторный запрос с тем же order_id, активом, суммой, external_user_id, return_url и cancel_url не создаёт второй инвойс и не возвращает ошибку. Ответом будет уже существующий инвойс с кодом 200. Поэтому запрос можно безопасно повторять после таймаута. Одновременные запросы с одним order_id тоже создают один инвойс.

Сумма повтора сравнивается с ценой amount_requested, а не с amount_expected: повтор присылает ту же цену, а комиссия, добавленная к ней при создании, — условие уже выставленного инвойса. Ответ на повтор показывает инвойс с условиями, записанными при создании, даже если ставка с тех пор изменилась.

Запрос с тем же order_id, но другой суммой, активом, пользователем или адресами возврата отклоняется с кодом 409 order_id_conflict: это другой платёж, а не повтор. Повтор принятого запроса возвращает инвойс, даже если оператор с тех пор сменил адреса мерчанта: переопределения проверяются при создании.

Ошибки

Пример

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}'

{
  "invoice_id": "6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "order_id": "ord_1001",
  "status": "created",
  "asset": "USDT_TRON",
  "network": "tron",
  "address": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "amount_requested": "49.900000",
  "amount_expected": "49.900000",
  "amount_received": "0.000000",
  "amount_credited": "0.000000",
  "fees": {
    "service": { "payer": "merchant", "percent": "1.00", "amount": "0.000000" },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "pending" }
  },
  "external_user_id": null,
  "return_url": null,
  "cancel_url": null,
  "checkout_url": null,
  "expires_at": "2026-09-11T21:03:05.531Z",
  "created_at": "2026-09-11T20:03:05.531Z",
  "deposits": []
}

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

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

Инвойс другого мерчанта для вызывающего не существует: ответ 404 invoice_not_found. Идентификатор не в формате UUID — 400 validation_failed.

Поля элемента deposits:

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

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

Статусы

Схема статусов и её обоснование — в ADR-0006.

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

Правила:

• Вовремя пришёл перевод или нет, решает время блока, в который он попал, а не момент подтверждения. Перевод, отправленный за минуту до дедлайна, считается своевременным, даже если подтверждения наберутся позже.
• Инвойс становится underpaid или expired только после того, как сервис просканировал блоки после дедлайна и все своевременные переводы подтвердились. Поэтому инвойс может оставаться в created или seen немного дольше дедлайна.
• До дедлайна переводы на адрес инвойса суммируются: первый перевод не считается окончательным.
• Переплата не отдельный статус: инвойс становится confirmed, а amount_received больше amount_expected.
• Перевод, исчезнувший из цепи при реорганизации, перестаёт учитываться: инвойс без других переводов возвращается в created, мерчант получает deposit.orphaned. Если перевод затем снова попадает в цепь, он учитывается заново. В этом редком случае инвойс может выйти из expired или underpaid обратно в seen.

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

Режим per_user

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

Сумма, с которой сравнивается перевод, — amount_expected: если комиссию сервиса платит покупатель, это цена вместе с комиссией.

Комиссии

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

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

Поля

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

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

Пример: цена 100 USDT, ставка 1%, комиссию платит покупатель.

Интеграция сравнивает свою цену с amount_requested, а покупателю показывает amount_expected: только эта сумма закрывает инвойс.

Суммы

Суммы передаются строками в единицах актива, например "49.900000". JSON-числа для сумм не используются: при разборе в число с плавающей точкой копейки теряются. Число знаков после запятой у каждого актива своё: у USDT в TRON — 6, у USDT в BNB Chain — 18.