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