# Життєвий цикл рахунку

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

## Статуси рахунку

| Статус | Значення в API | Опис | Бере участь у пошуку платежів |
| --- | --- | --- | --- |
| Неоплачений | `unpaid` | Рахунок виставлено, строк оплати не минув, оплата не надійшла | Так |
| Оплачений | `paid` | Платіж знайдено та прив’язано до рахунку | Ні |
| Прострочений | `expired` | Минув строк оплати, платіж не надійшов | Так, ще одну годину після закінчення |
| Скасований | `canceled` | Рахунок скасував продавець вручну або через API | Ні |

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

* **Створення рахунку.** Рахунок одразу отримує статус «Неоплачений».
* **Неоплачений → Оплачений.** Надійшов платіж на точну суму рахунку, або продавець прив’язав платіж вручну.
* **Неоплачений → Прострочений.** Минув строк оплати, платіж не надійшов.
* **Неоплачений → Скасований.** Продавець скасував рахунок.
* **Прострочений → Оплачений.** Платіж надійшов протягом години після закінчення строку та був знайдений автоматично, або продавець прив’язав його вручну.
* **Скасований.** Кінцевий стан, зворотного переходу немає.

Рахунок у статусі «Оплачений» теж не змінює стану — повторно оплатити або скасувати його не можна.

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

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

До закінчення строку покупець бачить платіжну форму й може оплатити рахунок. Після закінчення рахунок переходить у статус «Прострочений», і платіжна форма більше не пропонує оплату.

В обох крайнощів своя ціна. Короткий строк ризикований у повільних мережах — покупець може не встигнути оплатити. Довгий збільшує розрив між курсом на момент виставлення рахунку й курсом на момент оплати.

## Строк пошуку платежів

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

Звідси правило для інтеграторів: не відхиляйте сповіщення про оплату через строк, що минув, — така перевірка відсікає частину реальних платежів.

## Скасування рахунку

Рахунок можна скасувати, якщо в ньому допущено помилку. Скасування можливе за дотримання двох умов:

* Рахунок не оплачено — тобто він у статусі «Неоплачений»
* Платіжну сторінку рахунку ніхто не відкривав, лічильник переглядів дорівнює нулю

Друга умова захищає від скасування рахунку, який покупець уже бачив і, можливо, почав оплачувати.

Скасування незворотне. Скасований рахунок виключається з пошуку платежів, і прив’язати до нього платіж не можна навіть вручну. Якщо оплата ймовірна, дочекайтеся закінчення строку замість скасування — прострочений рахунок закрити платежем ще можна.

## Що фіксується під час створення, а що перераховується під час оплати

Під час створення рахунку сервіс конвертує фіатну суму в криптовалюту за поточним курсом і фіксує отримані суми за рахунком. Саме ці суми бачить покупець, і саме їх сервіс шукає в блокчейні. Курс після цього на них не впливає: хоч скільки часу мине, покупець платить рівно зафіксовану суму.

У момент оплати перераховуються облікові суми:

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

Через рух курсу ці значення можуть відрізнятися від початкових навіть за точної оплати. Для звірки із замовленням у магазині використовуйте `amountFiat` — це єдина сума, яка залишається незмінною.

## Сповіщення протягом життя рахунку

Сповіщення налаштовуються окремо для кожного проєкту. За рахунком їх два:

* **Вхідний платіж (Incoming payment).** Надсилається на email і в Telegram у разі виявлення будь-якої вхідної транзакції на ваш гаманець, незалежно від того, прив’язалася вона до рахунку чи ні.
* **Рахунок оплачено (Invoice paid).** Надсилається на email, у Telegram і на Webhook URL у момент переходу рахунку в статус «Оплачений» — і за автоматичної прив’язки, і за ручної.

Звідси просте діагностичне правило: надійшло сповіщення про вхідний платіж, але слідом не надійшло сповіщення про оплачений рахунок — отже, платіж не прив’язався через розбіжність у сумі й потребує ручної обробки.

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

У налаштуваннях проєкту можна вказати дві адреси, на які покупець повертається з платіжної сторінки:

* **Successful URL** — автоперехід після оплати рахунку
* **Unsuccessful URL** — автоперехід у разі відкриття простроченого або скасованого рахунку

Кожна адреса вмикається окремо. Якщо адресу не задано, покупець залишається на платіжній сторінці й бачить статус рахунку.

До адреси додається параметр `uid` — ідентифікатор рахунку для покупця: `https://example.com/order/success?uid=AFhygKX21ecd`. За ним магазин знаходить замовлення й показує покупцеві свою сторінку.

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