Прив’язка платежів і розбіжність сум
Розділ описує, за яким правилом сервіс пов’язує вхідну транзакцію в блокчейні з виставленим рахунком, що відбувається в разі розбіжності суми та як продавцеві діяти в такому разі.
Статуси рахунку, строки й переходи між станами описано в розділі Життєвий цикл рахунку.
Правило збігу суми
Під час створення рахунку сервіс конвертує фіатну суму в криптовалюту й фіксує отримані суми за рахунком. Саме вони стають ідентифікатором платежу: покупець бачить їх на платіжній формі, а сервіс шукає в блокчейні транзакцію рівно на таку суму.
Сума платежу має збігатися із сумою рахунку один в один. Допуску немає. Сума до сплати формується з точністю до 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.
Умови прив’язки
Прив’язка можлива, лише якщо виконано всі умови одночасно:
- Рахунок у статусі «Неоплачений» або «Прострочений». Скасовані та вже оплачені рахунки прив’язати не можна.
- Платіж ще не прив’язаний до іншого рахунку. Один платіж може бути пов’язаний лише з одним рахунком.
- Платіж надійшов на гаманець, задіяний у цьому рахунку.
- Платіж потрапляє у вікно доступних платежів — доба до та доба після створення рахунку.
Вікно ширше за строк дії рахунку, і з цього випливають дві можливості: прив’язати платіж можна до вже простроченого рахунку, а також прив’язати платіж, що надійшов раніше, ніж було створено рахунок. Останнє зручно, коли покупець переказав гроші з власної ініціативи, а рахунок виставлено за фактом надходження.
Що відбувається після прив’язки
- Рахунок переходить у статус «Оплачений» — так само, як за автоматичної прив’язки.
- Webhook надсилається обов’язково. Сповіщення йде за кожного переходу рахунку в «Оплачений», незалежно від способу прив’язки.
- Сума рахунку в USD перераховується за фактом. Поле
amountFiatUSDперезаписується фактично отриманою сумою за курсом на момент прив’язки. Початкова сума вamountFiatне змінюється. - Комісія перераховується від фактичної суми. Обчислюється за ставкою тарифу проєкту від суми, яку ви отримали.