Интеграция с 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, выводы — с какой периодичностью и куда отдавать данные.
• Ограничения инфраструктуры: где разворачиваются сервисы, кто администрирует узлы сети, что требуется по хранению истории операций и доступу к ней.
• Сценарии сбоев: недошедший перевод, повторная отправка, расхождение баланса — как они обрабатываются сейчас и кто разбирает такие случаи.
• Кто на вашей стороне отвечает за безопасность ключей и подтверждает изменения на боевом контуре.
• Желаемые сроки запуска и дата, к которой приём платежей должен работать в рабочем режиме.

В ответ вы получаете оценку объёма работ с разбивкой по этапам, план внедрения с контрольными точками и перечень требований к вашей стороне — что подготовить до старта. Опишите задачу как есть, с текущими ограничениями и сроками: обсудим детали и вернёмся с планом.