Інтеграція з TON API: приймання платежів, баланси Jettons за 1-2 дні

Інтеграція TON API: де ламається облік надходжень

Інтеграція TON API майже завжди починається з простого сценарію: отримали подію про переказ — зарахували суму. На практиці це два незалежні процеси: транзакція потрапляє в блок і отримує підтвердження, а облік у вашій системі оновлюється окремим викликом.

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

Далі — подвійне зарахування. Одна й та сама подія надходить повторно: сервіс перезапустився під час оновлення, сповіщення продублювалося, спрацював повторний запит після таймауту.

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

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

Гірше — «завислі» перекази: відправлення пройшло, підтвердження не надійшло, платіж не видно ні в обліку, ні у звіті, а клієнт уже написав у підтримку.

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

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

Що дає інтеграція напряму: швидкість і звірка балансів

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

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

Другий шар — ідемпотентна обробка: кожна подія надходить з унікальним ідентифікатором переказу, і повторна доставка не створює другого зарахування. Так іде клас відмов із дублями й завислими переказами між внутрішнім обліком і мережею.

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

Автоматична звірка йде на тому самому потоці подій: сервіс періодично зіставляє журнал операцій зі станом адрес і балансами Jetton-гаманців, а розбіжності потрапляють у звіт до того, як їх помітить клієнт або підтримка.

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

Повідомлення про надходження йдуть в інтерфейс, на пошту або у внутрішню систему замовника, щоб зарахування підхоплювалося бізнес-логікою одразу.

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

Способи приймання платежів: кастодіальний, некастодіальний, гібридний

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

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

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

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

Порядок впровадження: від аудиту схеми до передачі в підтримку

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

1. Аудит поточної схеми. Розбираємо, як сьогодні обліковуються надходження: який реєстр операцій вважається джерелом істини, які адреси й контракти задіяні, де розходяться виписки та внутрішній облік. Результат — карта поточного стану зі списком розбіжностей, вона ж точка приймання етапу.
2. Схема потоків платежів. Проєктуємо адресацію вхідних переказів: унікальний ідентифікатор платежу або окрема адреса на клієнта, правила зіставлення переказу із замовленням, обробку недоплат і повторів, читання балансів Jettons. Затверджена схема — приймання етапу.
3. Тестова мережа. Піднімаємо контур на тестових монетах і проганяємо сценарії: успішний платіж, недоплата, повторне відправлення, переказ не тим токеном, платіж за простроченим рахунком.
4. Перевірка на відмову. Обриваємо зв’язок із вузлом, дублюємо повідомлення про транзакцію, затримуємо підтвердження. Мета — один переказ не створює другий платіж, а розбіжності підхоплює звірка за розкладом.
5. Приймання за регламентом. Звіряємо баланси й реєстр операцій за чек-лістом, кожну розбіжність розбираємо до нуля. Етап не закрито, поки контрольні суми не збіглися.
6. Передача в підтримку. Віддаємо документацію, схему потоків, доступи, журнали й регламент реакції на інциденти, навчаємо чергову зміну.

Після цього інтеграція TON API живе як звичайний сервіс — її можна розвивати, не перебудовуючи платіжний контур.

Конфігурації, схеми й регламенти, які залишаються у вас

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

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

• Документація з інтеграції — які методи викликаємо для створення рахунку, відстеження надходження й читання балансів Jettons; структура запитів і відповідей, розбір кодів помилок і однозначне правило, як на кожен із них реагувати.
• Схема зберігання ключів — де фізично лежать ключі гаманця, хто і за яким алгоритмом отримує до них доступ, порядок ротації та послідовність дій за підозри на компрометацію.
• Політики доступу — ролі сервісів і людей, мінімально необхідні права, розділення контурів приймання платежів і виведення коштів, щоб утеча одного доступу не відкривала весь гаманець.
• Регламент обробки збоїв — поведінка за недоступності зовнішніх вузлів і затримки підтвердження, правила повторних спроб, момент, з якого платіж вважається фінальним, і порядок звірки розбіжностей.
• Інструкція для підтримки — розбір типових звернень (транзакція не видна, сума не зійшлася, статус завис), де дивитися журнали, що відповідати користувачеві й на якому кроці підключати інженерів.
• Схема потоків і станів — шлях від виставлення рахунку до зарахування з позначеними точками збереження стану: після перезапуску сервісу жоден платіж не губиться й не задвоюється.
• Чек-ліст приймання й оновлень — набір перевірок після змін на стороні зовнішньої мережі та перелік метрик, які мають бути на моніторингу, щоб деградацію помічати до скарг клієнтів.

Усе складаємо у ваш репозиторій у тому форматі, який прийнятий у вашій команді, — з історією змін і відповідальними за розділи. Далі система живе за вашими правилами, а не за нашою пам’яттю про те, як її збирали.

Кейс: приймання платежів без ручних звірок і загублених переказів

До нас звернувся сервіс цифрових товарів: оплату в TON і жетонах він приймав, але кожен переказ підтверджував оператор підтримки.

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

У вечірні години черга сягала десятків переказів, а частка операцій, що вимагали ручної перевірки, трималася на 100% — без людини не проходив жоден платіж.

Що змінили

Зібрали приймання платежів через програмний інтерфейс мережі: підписка на вхідні перекази, зіставлення за адресою, сумою та призначенням, автоматичне зарахування з окремим порогом ручної перевірки для великих сум.

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

Що вийшло

• частка операцій із ручною перевіркою — з 100% до 4%, решту закривається автоматично за хвилини;
• час реакції на розбіжність балансів — з кількох годин до 10-15 хвилин, причому про проблему дізнаємося раніше за клієнта;
• вечірня черга переказів зникла як явище: підтримка займається спірними випадками, а не звіркою.

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

Якщо приймання платежів уже працює через сторонній сервіс

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

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

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

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

Окремо проходимо пограничні випадки — платежі в момент відключення сервісу, часткові надходження, повторні повідомлення, завислі підтвердження.

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

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

Технічні сумніви: підтвердження, ліміти, доступ до ключів

Перед стартом інтеграції TON API інженери ставлять одні й ті самі п’ять питань. Нижче — короткі відповіді: як ми закриваємо кожен пункт, не переписуючи ваш продукт і не забираючи контроль над коштами.

Чи є ліміти на виведення?

Мінімальну суму, добовий ліміт та черговість заявок задаємо політикою на вашій стороні. У разі відмови заявка не зникає: вона залишається в журналі із причиною.

Чи отримуєте ви доступ до приватних ключів?

Ні. Підпис залишається у вашому контурі — підключаємося ключем з обмеженими правами й бачимо тільки адреси та публічні дані.

Що з повторною обробкою операцій?

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

Що робити за недоступності вузла мережі?

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

Обговоримо завдання: розберемо схему й повернемося з планом робіт

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

Із цього складається план впровадження з реалістичними термінами запуску, а не «середня оцінка по ринку».

Надішліть у вільній формі те, що вже є:

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

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