Чому приймання платежів TON ламається на проді
Приймання платежів TON виглядає тривіально: згенерували адресу, показали QR, дочекалися транзакції. На проді з'ясовується, що мережа підтверджує оплату асинхронно — стан гаманця змінюється не в момент натискання кнопки, а коли переказ потрапить у блок.
Класика — платіж пішов, а підтвердження не дійшло: індексатор відстав, вебхук загубився під час викатки, обробник упав на несподіваній відповіді. Зарахування не пройшло, баланс не змінився, а звернення до підтримки надходить раніше за транзакцію.
Окремий сценарій — завислий переказ: комісію виставлено нижче за поточне навантаження, і повідомлення висить у черзі — ні підтвердження, ні відмови.
Адреса теж «пливе»: під час генерації нової адреси під кожен рахунок відповідність «адреса — замовлення» губиться при перезапуску сервісу, ротації гаманця або в кеші.
У TON Connect платник переказує зі свого гаманця, і пов'язати надходження з рахунком можна лише за коментарем і тілом повідомлення. У Jetton додається шар: надходить не монета, а переказ із корисним навантаженням, і без розбору цього поля платіж не зіставити із замовленням.
Звідси два дорогі класи відмов: ручна звірка платежів і подвійне зарахування. Повторна доставка вебхука або ретрай обробника нараховують суму двічі, а розбіжності шукають за випискою вже після скарги клієнта.
Розбираємо, як це закривається: ідемпотентність на рівні події, курсор за вхідними переказами та алерти на затримку підтверджень.
Що змінюється після впровадження: швидкість, звірка, відмови
Ефект впровадження вимірюється не фактом підключення гаманця, а тим, скільки платежів система закриває сама.
До автоматизації кожне надходження звіряли вручну: суму та коментар до переказу зіставляли із замовленням, а завислий переказ знаходився лише тоді, коли клієнт писав до підтримки.
TON Connect із серверним підтвердженням переказів і обробником Jetton переносить цю роботу в код — інженери налаштовують зарахування за подією з мережі, а не за випискою.
Чек-ліст, за яким приймаємо результат:
- Частка автоматично зарахованих платежів — 95%+ від загальної кількості. У ручний розбір потрапляють лише нестандартні випадки: переказ без коментаря, недоплата, платіж не на ту адресу.
- Час підтвердження платежу — зарахування налаштовуємо на потрібну кількість підтверджень мережі; баланс замовлення оновлюється в межах десятків секунд замість звірки раз на годину.
- Реакція на завислий переказ — фоновий спостерігач перевіряє статус повторно і піднімає оповіщення за хвилини, а не після звернення клієнта.
- Частка ручних операцій — падає з третини транзакцій до одиниць відсотків; бухгалтерія отримує готовий журнал із зіставленням «транзакція — замовлення — сума».
- Клас відмов, що зник — зарахування на чужий рахунок, дубль при повторному надсиланні, загублений платіж без коментаря закриваються адресою-на-рахунок і захистом від повторного зарахування за хешем.
- Jetton на тих самих рейках — токенні платежі йдуть через той самий контур зарахування, з коректним урахуванням десяткових знаків.
Варіанти інтеграції: TON Connect, Jetton, пряме надсилання
Режим приймання задає, скільки логіки залишається на боці сервісу. Підключення гаманця віддає підпис транзакції клієнту, переказ токена потребує окремої звірки балансу, а пряме надсилання на адресу — найпростіший сценарій, але й найсліпіший.
Нижче — порівняння за трьома осями: що бачить платіжний сервіс, що доводиться підтверджувати вручну і як виглядає повернення.
| Варіант | Коли підходить | Обмеження інтеграції |
|---|---|---|
| TON Connect (підключення гаманця) | Підписки, особистий кабінет, оплата всередині інтерфейсу з підтвердженням у гаманці | Тримати актуальний список сумісних застосунків, коректно обробляти відмову користувача, стежити за зміною мережі в гаманці |
| Переказ у токені (Jetton) | Розрахунки у власному активі, коли номінал не збігається з базовою монетою | Перевіряти, що надійшов саме ваш токен, а не копія зі схожим іменем; окремо враховувати десяткові знаки й адресу відправника |
| Пряме надсилання на адресу | Донати, поповнення балансу, приймання без користувацького інтерфейсу | Зіставляти платіж із замовленням за сумою та коментарем, вручну розбирати спірні перекази, підтвердження від платника немає |
На практиці режими комбінують: підключення гаманця закриває основний потік, пряме надсилання працює резервним каналом, а токен-перекази вмикають лише там, де розрахунок у базовій монеті незручний.
Спільним залишається одне — власний журнал вхідних транзакцій з обробкою, стійкою до повторної доставки, інакше один переказ перетворюється на два зарахування.
Як відбувається впровадження: від аудиту до передачі регламентів
Роботу ведемо етапами: спочатку фіксуємо, як надходять платежі та де підтверджується факт оплати, потім налаштовуємо приймання, далі перевіряємо на реальних переказах і передаємо регламенти.
Порядок не змінюємо — пропущений аудит зазвичай спливає вже на перевірці, коли переробляти схему дорожче.
Аудит і схема
- Аудит платіжних потоків. Розбираємо типи оплат — разові, підписки, поповнення балансу, повернення — і дивимося, як факт оплати пов'язується із замовленням в обліковій системі.
- Схема підтверджень. Домовляємося, що вважаємо оплатою: запис переказу в блоці, кількість підтверджень або подію від гаманця. Від цього залежать момент зміни статусу замовлення та логіка скасувань із повторами.
- Зіставлення платежу із замовленням. Обираємо спосіб приймання — прямий переказ на адресу, підключення гаманця через TON Connect або приймання жетонів — і фіксуємо ідентифікатор, який не загубиться при паралельних замовленнях.
Налаштування та перевірка
- Налаштування приймання та автоматизації. Сервіс слухає мережу, зіставляє перекази із замовленнями та змінює їхній статус; окремо налаштовуємо повторні перевірки для транзакцій, які підтверджуються не миттєво.
- Тестові перекази. Спочатку прогін у тестовій мережі, потім реальні перекази мінімальних сум: успіх, недоплата, переказ без ідентифікатора, повторне надсилання. Кожен сценарій — рядок у звіті зі статусом.
Приймання та передача
- Приймання. Звіряємо статуси замовлень із рухом коштів, перевіряємо журнали, повідомлення та поведінку при недоступності вузла.
- Передача регламентів. Віддаємо інструкції з моніторингу, порядок дій при збої, правила звірки та додавання нових жетонів — команда супроводжує приймання платежів сама.
Що залишається у вас: конфігурація, ключі, документація
Передаємо не доступ до сервера, а відтворюваний набір артефактів: із ним ваша команда приймає платежі, змінює параметри та розбирає інциденти без нашої участі. Усе, що стосується руху коштів, фіксується письмово — у платежах усні домовленості не працюють.
- Конфігурація приймання: файли оточення з адресою отримувача, списком прийнятних джетонів, лімітами на суму та кількістю підтверджень мережі, з коментарями про те, що і коли змінювати.
- Схема адрес: який гаманець гарячий, де холодне зберігання, як налаштовано виведення коштів і куди йде комісія.
- Керування ключами: де лежать приватні ключі та мнемоніки, хто до них допущений, як відбувається ротація і що робити при компрометації. Ключі залишаються у вас — ми працюємо на тестовому контурі.
- Політики доступу: ролі та мінімальні права, обов'язкове друге підтвердження для виведення, журнал операцій із зазначенням ініціатора та часу.
- Правила звірки: як вхідна транзакція зіставляється із замовленням, з якого моменту оплата вважається підтвердженою і які розбіжності йдуть у ручний розбір.
- Документація: схема потоків платежів, опис інтеграції TON Connect на боці інтерфейсу, перелік контрактів з адресами, порядок роботи з тестовою мережею.
- Інструкції для підтримки: готові сценарії на часті звернення — платіж не надійшов, сума менша за очікувану, користувач закрив гаманець до підтвердження, зависле виведення.
- Регламент змін: як викочується нова конфігурація, де зберігається попередня версія і як відкотитися за один крок.
Кейс: ручна звірка скоротилася, завислі платежі зникли
Як було
До автоматизації приймання платежів TON виглядало так: оператор відкривав оглядач мережі, шукав вхідний переказ, зіставляв коментар до транзакції з номером замовлення і вручну змінював статус в обліковій системі.
На потоці в кілька тисяч замовлень на місяць через руки проходило близько 40% зарахувань, а поза робочими годинами платіж чекав підтвердження до ранку.
Завислі платежі — розбіжність суми, друкарська помилка в коментарі, повторне надсилання — сягали 4-6% і розбиралися в листуванні з підтримкою. Кожен такий випадок вимагав ручної звірки за журналом і затягував закриття замовлення.
Що змінили і що отримали
Підключили TON Connect для підпису гаманцем, а зарахування перевели на індексатор: сервіс слухає мережу, звіряє вхідні перекази з відкритими рахунками і закриває рахунок автоматично.
Для Jetton додали звірку за адресою майстер-контракту токена та його точністю — без цього однакові суми в різних токенах склеювалися.
Кожному рахунку присвоєно унікальний ідентифікатор у коментарі до переказу, запис ідемпотентний за хешем транзакції, зарахування йде після заданої кількості підтверджень, а необроблені випадки йдуть у чергу з повторними спробами та оповіщенням чергового.
Частка автоматичних підтверджень зросла до 97-99%: ручна звірка залишилася лише для спірних переказів — незбіг суми, платіж без коментаря, повернення.
Середній час зарахування скоротився з десятків хвилин до 30-90 секунд і перестав залежати від графіка операторів, частка завислих платежів упала нижче 0,3%.
Чим відрізняється нативний переказ від Jetton-переказу?
У мережі TON нативний переказ — рух базової монети: факт розрахунку збігається зі зміною балансу.
Щоб зарахувати платіж, достатньо дочекатися включення транзакції в блок і потрібної кількості підтверджень — другого виклику контракту немає, платіж або пройшов повністю, або не пройшов.
Jetton — токен-контракт: переказ йде повідомленням у токен-гаманець відправника, той списує баланс і повідомляє гаманець отримувача. Межа підтвердження тут не перша транзакція, а саме повідомлення: поки баланс отримувача не оновився, зараховувати платіж не можна.
На практиці це два різні контури приймання платежів. Для нативу сервіс слухає вхідні транзакції на адресу та підтверджує їх за кількістю блоків. Для Jetton він або чекає повідомлення з коментарем до переказу, або звіряє баланс токен-гаманця й зіставляє переказ за ідентифікатором.
Якщо платіж іде з біржі, коментар часто губиться — тому в одному контурі видаємо унікальну адресу під кожен рахунок, у другому вимагаємо обов'язковий коментар.
Комісії мережі теж поводяться по-різному. У нативному переказі газ платить відправник, отримувачу резервувати нічого.
У Jetton відправник платить двічі — за переказ і за доставку повідомлення: докладено мало базової монети, жетони дійшли, повідомлення ні, і платіж спливає лише на звірці. На вашому токен-гаманці потрібен запас базової монети, інакше не піде ні повернення, ні виведення.
Повернення. Для нативу повернення — звичайна транзакція з гарячого гаманця: одна комісія, передбачуваний результат. Для Jetton повернення йде з токен-гаманця, комісії за доставку списуються на боці відправника, і сума повернення може виявитися меншою за початкову.
Тому в обидва контури закладаємо ідемпотентну звірку за ідентифікатором транзакції та чергу «завислих» платежів, а обираємо за сценарієм: натив — де важливі простота й масові виплати, Jetton — де платіж має йти в токені з прив'язкою до зовнішнього активу.
Часті технічні сумніви та відповіді
Сумніви на прийманні повторюються раз у раз: як не зарахувати один переказ двічі, що буде при зміні адреси гаманця, хто з команди бачить операції і як усе це сходиться з поточним обліком. Це ті місця, де інтеграція або тримає потік, або починає вимагати ручних звірок — розбираємо кожен.
Платіж підтвердився двічі — зарахуєте двічі?
Ні. Кожне надходження отримує унікальний ідентифікатор, і обробник звіряє його з журналом до зарахування. Повторне підтвердження того самого переказу обробляється ідемпотентно: замовлення оновлюється один раз, решта викликів повертають уже збережений результат.
Ми змінили адресу приймання — старі платежі не загубляться?
Ні, якщо адреси зберігаються довідником, а не вписані в логіку. Ведемо реєстр відповідностей «адреса — гаманець — призначення», історія залишається доступною, а нова адреса підключається без правок коду. У перехідний період опитуємо обидві адреси паралельно.
Як це сходиться з поточним обліком?
Вивантаження йде у форматі, який приймає ваша облікова система: ідентифікатор, сума, призначення, статус. Звірка виконується автоматично, розбіжності потрапляють в окремий список із причиною, а не в ручний розбір. Якщо облік у закритому контурі — віддаємо файл або передаємо дані за розкладом.
Хто зі співробітників отримає доступ до операцій?
Ролі налаштовуються за мінімальними правами: бухгалтерія бачить вивантаження та статуси, підтримка — лише конкретний платіж за номером замовлення, ключі виведення залишаються в одного відповідального. Кожна дія пишеться в журнал, тож видно і автора, і час.
Обговоримо задачу: повернемося з оцінкою та планом робіт
Щоб повернутися з точною оцінкою робіт, а не з вилкою «на око», нам потрібен невеликий набір вихідних даних щодо вашої схеми приймання. Продові ключі та доступи на цьому етапі не потрібні — достатньо опису того, як платежі влаштовані зараз і що має вийти в результаті.
- схема приймання: підключення гаманця через TON Connect у застосунку або на сайті, оплата за адресою або переказом жетонів;
- як формується адреса під платіж: статична, по одній на операцію, з ідентифікатором у коментарі;
- звідки береться підтвердження зарахування: власний вузол, публічний оглядач блоків або повідомлення провайдера;
- що відбувається при недоплаті, переплаті, переказі без коментаря та повторному надсиланні;
- обсяги: кількість платежів за добу та пікове навантаження, скільки жетонів і адрес обслуговується;
- облік і звірка: вивантаження операцій, зіставлення із внутрішньою базою, ролі та доступи співробітників;
- обмеження: де зберігаються ключі, чи є вимоги щодо розділення середовищ і аудиту операцій.
Із цим набором ми повертаємося з оцінкою робіт і планом впровадження: черговість етапів, що закриваємо першим, де точки перевірки і що потрібно буде від вашої сторони. Опишіть задачу в зручному вигляді — розберемо схему приймання платежів і запропонуємо рішення.
