# Прив’язка платежів і розбіжність сум

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

Статуси рахунку, строки й переходи між станами описано в розділі [Життєвий цикл рахунку](./invoice-lifecycle.md).

## Правило збігу суми

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

**Сума платежу має збігатися із сумою рахунку один в один. Допуску немає.** Сума до сплати формується з точністю до 2 знаків після коми для стейблкоїнів USDT і USDC та до 8 знаків для решти криптовалют, і платіж, що надійшов, порівнюється з нею точно. Будь-яке відхилення — недоплата чи переплата, навіть на мінімальну величину — означає, що автоматичної прив’язки не відбудеться.

**Приклад.** Рахунок на 100.00 USD виставлено із зафіксованою сумою 100.12 USDT.

| Сума платежу, що надійшов | Результат |
| --- | --- |
| 100.12 USDT | Рахунок автоматично переходить у статус «Оплачений» |
| 100.11 USDT | Автоматичної прив’язки немає |
| 100.50 USDT | Автоматичної прив’язки немає |

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

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

## Що відбувається в разі розбіжності суми

Сервіс фіксує факт надходження коштів, але не виконує жодних дій із рахунком:

* **Рахунок не змінює статусу.** Він залишається актуальним до закінчення строку оплати. Покупець, як і раніше, може закрити його правильною сумою, доки не минув строк пошуку.
* **Webhook не надсилається.** Сповіщення на Webhook URL іде виключно в момент переходу рахунку в статус «Оплачений».
* **Часткова оплата не враховується.** Сервіс не розрізняє недоплату й не веде обліку залишку за рахунком.
* **Платежі не сумуються.** Якщо покупець після недоплати надішле різницю, якої бракує, другою транзакцією, ці два платежі не будуть складені. Обидва залишаться окремими неприв’язаними платежами.
* **Переплата не повертається автоматично.** Кошти надходять безпосередньо на ваш гаманець, питання повернення різниці покупцеві вирішується поза сервісом.

Проміжних статусів на кшталт «Частково оплачений» або «Переплата» в сервісі не передбачено.

## Як продавець дізнається про проблему

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

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

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

Неприв’язані платежі можна знаходити й програмно. Метод `payments/list` повертає платежі за всіма вашими гаманцями, і в платежу, не прив’язаного до рахунку, у відповіді немає блока `invoice`. Це й є кандидати на ручну прив’язку: зіставте суму й час з очікуваним рахунком і викличте `invoices/bindPayment`.

## Ручна прив’язка платежу

Якщо ви впевнені, який платіж відповідає якому рахунку, прив’яжіть їх вручну — в особистому кабінеті в картці рахунку чи в списку платежів або через API методом `invoices/bindPayment`.

### Умови прив’язки

Прив’язка можлива, лише якщо виконано всі умови одночасно:

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

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

### Що відбувається після прив’язки

* **Рахунок переходить у статус «Оплачений»** — так само, як за автоматичної прив’язки.
* **Webhook надсилається обов’язково.** Сповіщення йде за кожного переходу рахунку в «Оплачений», незалежно від способу прив’язки.
* **Сума рахунку в USD перераховується за фактом.** Поле `amountFiatUSD` перезаписується фактично отриманою сумою за курсом на момент прив’язки. Початкова сума в `amountFiat` не змінюється.
* **Комісія перераховується від фактичної суми.** Обчислюється за ставкою тарифу проєкту від суми, яку ви отримали.