Життєвий цикл рахунку
Рахунок проходить шлях від створення до закриття або закінчення строку. Розділ описує, у яких станах він буває, як між ними переходить і що на кожному кроці може зробити продавець.
Статуси рахунку
| Статус | Значення в 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. За ним магазин знаходить замовлення й показує покупцеві свою сторінку.
Перехід на ці адреси оплату не підтверджує — покупець може відкрити посилання вручну. Видавайте товар за вебхуком або після перевірки статусу рахунку через API.