# Жизненный цикл счета

Счет проходит путь от создания до закрытия или истечения срока. Раздел описывает, в каких состояниях он бывает, как между ними переходит и что на каждом шаге может сделать продавец.

## Статусы счета

| Статус    | Значение в API | Описание                                                  | Участвует в поиске платежей      |
| --------- | -------------- | --------------------------------------------------------- | -------------------------------- |
| Актуален  | `unpaid`       | Счет выставлен, срок оплаты не истек, оплата не поступила | Да                               |
| Оплачен   | `paid`         | Платеж найден и привязан к счету                          | Нет                              |
| Просрочен | `expired`      | Истек срок оплаты, платеж не поступил                     | Да, еще один час после истечения |
| Отменен   | `canceled`     | Счет отменен продавцом вручную или через API              | Нет                              |

## Переходы между статусами

* **Создание счета.** Счет сразу получает статус «Актуален».
* **Актуален → Оплачен.** Поступил платеж на точную сумму счета, либо продавец привязал платеж вручную.
* **Актуален → Просрочен.** Истек срок оплаты, платеж не поступил.
* **Актуален → Отменен.** Продавец отменил счет.
* **Просрочен → Оплачен.** Платеж пришел в течение часа после истечения срока и был найден автоматически, либо продавец привязал его вручную.
* **Отменен.** Конечное состояние, обратного перехода нет.

Счет в статусе «Оплачен» тоже не меняет состояние — повторно оплатить или отменить его нельзя.

## Срок оплаты

Срок задается при создании счета и составляет от 30 минут до 12 часов. Допустимые значения: 30 минут, 1 час, 3 часа, 6 часов, 12 часов.

До окончания срока покупатель видит платежную форму и может оплатить счет. После истечения счет переходит в статус «Просрочен» и платежная форма больше не предлагает оплату.

У обеих крайностей своя цена. Короткий срок рискован в медленных сетях — покупатель может не успеть оплатить. Длинный увеличивает разрыв между курсом на момент выставления счета и курсом на момент оплаты.

## Срок поиска платежей

Поиск платежей продолжается еще час после истечения срока оплаты — с учетом медленных сетей, где транзакция может подтвердиться уже после того, как счет формально истек. Все это время счет отображается покупателю как просроченный, но при поступлении платежа на нужную сумму автоматически переходит в статус «Оплачен» со всеми уведомлениями.

Отсюда правило для интеграторов: не отклоняйте уведомление об оплате из-за истекшего срока — такая проверка отсекает часть реальных платежей.

## Отмена счета

Счет можно отменить, если в нем допущена ошибка. Отмена возможна при соблюдении двух условий:

* Счет не оплачен — то есть находится в статусе «Актуален»
* Платежную страницу счета никто не открывал, счетчик просмотров равен нулю

Второе условие защищает от отмены счета, который покупатель уже видел и, возможно, начал оплачивать.

Отмена необратима. Отмененный счет исключается из поиска платежей, и привязать к нему платеж нельзя даже вручную. Если оплата вероятна, дождитесь истечения срока вместо отмены — просроченный счет закрыть платежом еще можно.

## Что фиксируется при создании, а что пересчитывается при оплате

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

В момент оплаты пересчитываются учетные суммы:

| Поле                | Что происходит                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `amountFiat`        | Оригинальная сумма счета в фиатной валюте. Не меняется никогда                              |
| `amountFiatUSD`     | Перезаписывается фактически поступившей суммой, приведенной к USD по курсу на момент оплаты |
| `commissionFiatUSD` | Пересчитывается от нового значения `amountFiatUSD` по ставке тарифа проекта                 |

Из-за движения курса эти значения могут отличаться от исходных даже при точной оплате. Для сверки с заказом в магазине используйте `amountFiat` — это единственная сумма, которая остается неизменной.

## Уведомления по ходу жизни счета

Уведомления настраиваются отдельно для каждого проекта. По счету их два:

* **Входящий платеж.** Отправляется на email и в Telegram при обнаружении любой входящей транзакции на ваш кошелек, независимо от того, привязалась она к счету или нет.
* **Счет оплачен.** Отправляется на email, в Telegram и на Webhook URL в момент перехода счета в статус «Оплачен» — и при автоматической привязке, и при ручной.

Отсюда простое диагностическое правило: пришло уведомление о входящем платеже, но следом не пришло уведомление об оплаченном счете — значит платеж не привязался из-за расхождения в сумме и требует ручной обработки.

## Возврат покупателя на сайт магазина

В настройках проекта можно указать два адреса, на которые покупатель возвращается с платежной страницы:

* **Successful URL** — автопереход после оплаты счета
* **Unsuccessful URL** — автопереход при открытии просроченного или отмененного счета

Каждый адрес включается отдельно. Если адрес не задан, покупатель остается на платежной странице и видит статус счета.

К адресу добавляется параметр `uid` — идентификатор счета для покупателя: `https://example.com/order/success?uid=AFhygKX21ecd`. По нему магазин находит заказ и показывает покупателю свою страницу.

Переход на эти адреса оплату не подтверждает — покупатель может открыть ссылку вручную. Выдавайте товар по [вебхуку](./webhook-url/index.md) или после [проверки статуса](./api/index.md) счета через API.